1 //===- SectionMemoryManager.h - Memory manager for MCJIT/RtDyld -*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file contains the declaration of a section-based memory manager used by
11 // the MCJIT execution engine and RuntimeDyld.
13 //===----------------------------------------------------------------------===//
15 #ifndef LLVM_EXECUTIONENGINE_SECTIONMEMORYMANAGER_H
16 #define LLVM_EXECUTIONENGINE_SECTIONMEMORYMANAGER_H
18 #include "llvm/ADT/SmallVector.h"
19 #include "llvm/ADT/StringRef.h"
20 #include "llvm/ExecutionEngine/RTDyldMemoryManager.h"
21 #include "llvm/Support/Memory.h"
24 #include <system_error>
28 /// This is a simple memory manager which implements the methods called by
29 /// the RuntimeDyld class to allocate memory for section-based loading of
30 /// objects, usually those generated by the MCJIT execution engine.
32 /// This memory manager allocates all section memory as read-write. The
33 /// RuntimeDyld will copy JITed section memory into these allocated blocks
34 /// and perform any necessary linking and relocations.
36 /// Any client using this memory manager MUST ensure that section-specific
37 /// page permissions have been applied before attempting to execute functions
38 /// in the JITed object. Permissions can be applied either by calling
39 /// MCJIT::finalizeObject or by calling SectionMemoryManager::finalizeMemory
40 /// directly. Clients of MCJIT should call MCJIT::finalizeObject.
41 class SectionMemoryManager : public RTDyldMemoryManager {
43 /// This enum describes the various reasons to allocate pages from
44 /// allocateMappedMemory.
45 enum class AllocationPurpose {
51 /// Implementations of this interface are used by SectionMemoryManager to
52 /// request pages from the operating system.
55 /// This method attempts to allocate \p NumBytes bytes of virtual memory for
56 /// \p Purpose. \p NearBlock may point to an existing allocation, in which
57 /// case an attempt is made to allocate more memory near the existing block.
58 /// The actual allocated address is not guaranteed to be near the requested
59 /// address. \p Flags is used to set the initial protection flags for the
60 /// block of the memory. \p EC [out] returns an object describing any error
63 /// This method may allocate more than the number of bytes requested. The
64 /// actual number of bytes allocated is indicated in the returned
67 /// The start of the allocated block must be aligned with the system
68 /// allocation granularity (64K on Windows, page size on Linux). If the
69 /// address following \p NearBlock is not so aligned, it will be rounded up
70 /// to the next allocation granularity boundary.
72 /// \r a non-null MemoryBlock if the function was successful, otherwise a
73 /// null MemoryBlock with \p EC describing the error.
74 virtual sys::MemoryBlock
75 allocateMappedMemory(AllocationPurpose Purpose, size_t NumBytes,
76 const sys::MemoryBlock *const NearBlock,
77 unsigned Flags, std::error_code &EC) = 0;
79 /// This method sets the protection flags for a block of memory to the state
80 /// specified by \p Flags. The behavior is not specified if the memory was
81 /// not allocated using the allocateMappedMemory method.
82 /// \p Block describes the memory block to be protected.
83 /// \p Flags specifies the new protection state to be assigned to the block.
85 /// If \p Flags is MF_WRITE, the actual behavior varies with the operating
86 /// system (i.e. MF_READ | MF_WRITE on Windows) and the target architecture
87 /// (i.e. MF_WRITE -> MF_READ | MF_WRITE on i386).
89 /// \r error_success if the function was successful, or an error_code
90 /// describing the failure if an error occurred.
91 virtual std::error_code protectMappedMemory(const sys::MemoryBlock &Block,
94 /// This method releases a block of memory that was allocated with the
95 /// allocateMappedMemory method. It should not be used to release any memory
96 /// block allocated any other way.
97 /// \p Block describes the memory to be released.
99 /// \r error_success if the function was successful, or an error_code
100 /// describing the failure if an error occurred.
101 virtual std::error_code releaseMappedMemory(sys::MemoryBlock &M) = 0;
103 virtual ~MemoryMapper();
106 /// Creates a SectionMemoryManager instance with \p MM as the associated
107 /// memory mapper. If \p MM is nullptr then a default memory mapper is used
108 /// that directly calls into the operating system.
109 SectionMemoryManager(MemoryMapper *MM = nullptr);
110 SectionMemoryManager(const SectionMemoryManager &) = delete;
111 void operator=(const SectionMemoryManager &) = delete;
112 ~SectionMemoryManager() override;
114 /// \brief Allocates a memory block of (at least) the given size suitable for
117 /// The value of \p Alignment must be a power of two. If \p Alignment is zero
118 /// a default alignment of 16 will be used.
119 uint8_t *allocateCodeSection(uintptr_t Size, unsigned Alignment,
121 StringRef SectionName) override;
123 /// \brief Allocates a memory block of (at least) the given size suitable for
126 /// The value of \p Alignment must be a power of two. If \p Alignment is zero
127 /// a default alignment of 16 will be used.
128 uint8_t *allocateDataSection(uintptr_t Size, unsigned Alignment,
129 unsigned SectionID, StringRef SectionName,
130 bool isReadOnly) override;
132 /// \brief Update section-specific memory permissions and other attributes.
134 /// This method is called when object loading is complete and section page
135 /// permissions can be applied. It is up to the memory manager implementation
136 /// to decide whether or not to act on this method. The memory manager will
137 /// typically allocate all sections as read-write and then apply specific
138 /// permissions when this method is called. Code sections cannot be executed
139 /// until this function has been called. In addition, any cache coherency
140 /// operations needed to reliably use the memory are also performed.
142 /// \returns true if an error occurred, false otherwise.
143 bool finalizeMemory(std::string *ErrMsg = nullptr) override;
145 /// \brief Invalidate instruction cache for code sections.
147 /// Some platforms with separate data cache and instruction cache require
148 /// explicit cache flush, otherwise JIT code manipulations (like resolved
149 /// relocations) will get to the data cache but not to the instruction cache.
151 /// This method is called from finalizeMemory.
152 virtual void invalidateInstructionCache();
155 struct FreeMemBlock {
156 // The actual block of free memory
157 sys::MemoryBlock Free;
158 // If there is a pending allocation from the same reservation right before
159 // this block, store it's index in PendingMem, to be able to update the
160 // pending region if part of this block is allocated, rather than having to
162 unsigned PendingPrefixIndex;
166 // PendingMem contains all blocks of memory (subblocks of AllocatedMem)
167 // which have not yet had their permissions applied, but have been given
168 // out to the user. FreeMem contains all block of memory, which have
169 // neither had their permissions applied, nor been given out to the user.
170 SmallVector<sys::MemoryBlock, 16> PendingMem;
171 SmallVector<FreeMemBlock, 16> FreeMem;
173 // All memory blocks that have been requested from the system
174 SmallVector<sys::MemoryBlock, 16> AllocatedMem;
176 sys::MemoryBlock Near;
179 uint8_t *allocateSection(AllocationPurpose Purpose, uintptr_t Size,
182 std::error_code applyMemoryGroupPermissions(MemoryGroup &MemGroup,
183 unsigned Permissions);
186 MemoryGroup RWDataMem;
187 MemoryGroup RODataMem;
188 MemoryMapper &MMapper;
191 } // end namespace llvm
193 #endif // LLVM_EXECUTION_ENGINE_SECTION_MEMORY_MANAGER_H