/* Copyright (c) 2007, Google Inc. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are * met: * * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * Redistributions in binary form must reproduce the above * copyright notice, this list of conditions and the following disclaimer * in the documentation and/or other materials provided with the * distribution. * * Neither the name of Google Inc. nor the names of its * contributors may be used to endorse or promote products derived from * this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * * --- * Author: Joi Sigurdsson * Author: Scott Francis * * Definition of PreamblePatcher */ #ifndef GOOGLE_PERFTOOLS_PREAMBLE_PATCHER_H_ #define GOOGLE_PERFTOOLS_PREAMBLE_PATCHER_H_ #include "config.h" #include <windows.h> // compatibility shim #include "base/logging.h" #define SIDESTEP_ASSERT(cond) RAW_DCHECK(cond, #cond) #define SIDESTEP_LOG(msg) RAW_VLOG(1, msg) // Maximum size of the preamble stub. We overwrite at least the first 5 // bytes of the function. Considering the worst case scenario, we need 4 // bytes + the max instruction size + 5 more bytes for our jump back to // the original code. With that in mind, 32 is a good number :) #ifdef _M_X64 // In 64-bit mode we may need more room. In 64-bit mode all jumps must be // within +/-2GB of RIP. Because of this limitation we may need to use a // trampoline to jump to the replacement function if it is further than 2GB // away from the target. The trampoline is 14 bytes. // // So 4 bytes + max instruction size (17 bytes) + 5 bytes to jump back to the // original code + trampoline size. 64 bytes is a nice number :-) #define MAX_PREAMBLE_STUB_SIZE (64) #else #define MAX_PREAMBLE_STUB_SIZE (32) #endif // Determines if this is a 64-bit binary. #ifdef _M_X64 static const bool kIs64BitBinary = true; #else static const bool kIs64BitBinary = false; #endif namespace sidestep { // Possible results of patching/unpatching enum SideStepError { SIDESTEP_SUCCESS = 0, SIDESTEP_INVALID_PARAMETER, SIDESTEP_INSUFFICIENT_BUFFER, SIDESTEP_JUMP_INSTRUCTION, SIDESTEP_FUNCTION_TOO_SMALL, SIDESTEP_UNSUPPORTED_INSTRUCTION, SIDESTEP_NO_SUCH_MODULE, SIDESTEP_NO_SUCH_FUNCTION, SIDESTEP_ACCESS_DENIED, SIDESTEP_UNEXPECTED, }; #define SIDESTEP_TO_HRESULT(error) \ MAKE_HRESULT(SEVERITY_ERROR, FACILITY_NULL, error) class DeleteUnsignedCharArray; // Implements a patching mechanism that overwrites the first few bytes of // a function preamble with a jump to our hook function, which is then // able to call the original function via a specially-made preamble-stub // that imitates the action of the original preamble. // // NOTE: This patching mechanism should currently only be used for // non-production code, e.g. unit tests, because it is not threadsafe. // See the TODO in preamble_patcher_with_stub.cc for instructions on what // we need to do before using it in production code; it's fairly simple // but unnecessary for now since we only intend to use it in unit tests. // // To patch a function, use either of the typesafe Patch() methods. You // can unpatch a function using Unpatch(). // // Typical usage goes something like this: // @code // typedef int (*MyTypesafeFuncPtr)(int x); // MyTypesafeFuncPtr original_func_stub; // int MyTypesafeFunc(int x) { return x + 1; } // int HookMyTypesafeFunc(int x) { return 1 + original_func_stub(x); } // // void MyPatchInitializingFunction() { // original_func_stub = PreamblePatcher::Patch( // MyTypesafeFunc, HookMyTypesafeFunc); // if (!original_func_stub) { // // ... error handling ... // } // // // ... continue - you have patched the function successfully ... // } // @endcode // // Note that there are a number of ways that this method of patching can // fail. The most common are: // - If there is a jump (jxx) instruction in the first 5 bytes of // the function being patched, we cannot patch it because in the // current implementation we do not know how to rewrite relative // jumps after relocating them to the preamble-stub. Note that // if you really really need to patch a function like this, it // would be possible to add this functionality (but at some cost). // - If there is a return (ret) instruction in the first 5 bytes // we cannot patch the function because it may not be long enough // for the jmp instruction we use to inject our patch. // - If there is another thread currently executing within the bytes // that are copied to the preamble stub, it will crash in an undefined // way. // // If you get any other error than the above, you're either pointing the // patcher at an invalid instruction (e.g. into the middle of a multi- // byte instruction, or not at memory containing executable instructions) // or, there may be a bug in the disassembler we use to find // instruction boundaries. // // NOTE: In optimized builds, when you have very trivial functions that // the compiler can reason do not have side effects, the compiler may // reuse the result of calling the function with a given parameter, which // may mean if you patch the function in between your patch will never get // invoked. See preamble_patcher_test.cc for an example. class PERFTOOLS_DLL_DECL PreamblePatcher { public: // This is a typesafe version of RawPatch(), identical in all other // ways than it takes a template parameter indicating the type of the // function being patched. // // @param T The type of the function you are patching. Usually // you will establish this type using a typedef, as in the following // example: // @code // typedef BOOL (WINAPI *MessageBoxPtr)(HWND, LPCTSTR, LPCTSTR, UINT); // MessageBoxPtr original = NULL; // PreamblePatcher::Patch(MessageBox, Hook_MessageBox, &original); // @endcode template <class T> static SideStepError Patch(T target_function, T replacement_function, T* original_function_stub) { // NOTE: casting from a function to a pointer is contra the C++ // spec. It's not safe on IA64, but is on i386. We use // a C-style cast here to emphasize this is not legal C++. return RawPatch((void*)(target_function), (void*)(replacement_function), (void**)(original_function_stub)); } // Patches a named function imported from the named module using // preamble patching. Uses RawPatch() to do the actual patching // work. // // @param T The type of the function you are patching. Must // exactly match the function you specify using module_name and // function_name. // // @param module_name The name of the module from which the function // is being imported. Note that the patch will fail if this module // has not already been loaded into the current process. // // @param function_name The name of the function you wish to patch. // // @param replacement_function Your replacement function which // will be called whenever code tries to call the original function. // // @param original_function_stub Pointer to memory that should receive a // pointer that can be used (e.g. in the replacement function) to call the // original function, or NULL to indicate failure. // // @return One of the EnSideStepError error codes; only SIDESTEP_SUCCESS // indicates success. template <class T> static SideStepError Patch(LPCTSTR module_name, LPCSTR function_name, T replacement_function, T* original_function_stub) { SIDESTEP_ASSERT(module_name && function_name); if (!module_name || !function_name) { SIDESTEP_ASSERT(false && "You must specify a module name and function name."); return SIDESTEP_INVALID_PARAMETER; } HMODULE module = ::GetModuleHandle(module_name); SIDESTEP_ASSERT(module != NULL); if (!module) { SIDESTEP_ASSERT(false && "Invalid module name."); return SIDESTEP_NO_SUCH_MODULE; } FARPROC existing_function = ::GetProcAddress(module, function_name); if (!existing_function) { SIDESTEP_ASSERT( false && "Did not find any function with that name in the module."); return SIDESTEP_NO_SUCH_FUNCTION; } // NOTE: casting from a function to a pointer is contra the C++ // spec. It's not safe on IA64, but is on i386. We use // a C-style cast here to emphasize this is not legal C++. return RawPatch((void*)existing_function, (void*)replacement_function, (void**)(original_function_stub)); } // Patches a function by overwriting its first few bytes with // a jump to a different function. This is the "worker" function // for each of the typesafe Patch() functions. In most cases, // it is preferable to use the Patch() functions rather than // this one as they do more checking at compile time. // // @param target_function A pointer to the function that should be // patched. // // @param replacement_function A pointer to the function that should // replace the target function. The replacement function must have // exactly the same calling convention and parameters as the original // function. // // @param original_function_stub Pointer to memory that should receive a // pointer that can be used (e.g. in the replacement function) to call the // original function, or NULL to indicate failure. // // @param original_function_stub Pointer to memory that should receive a // pointer that can be used (e.g. in the replacement function) to call the // original function, or NULL to indicate failure. // // @return One of the EnSideStepError error codes; only SIDESTEP_SUCCESS // indicates success. // // @note The preamble-stub (the memory pointed to by // *original_function_stub) is allocated on the heap, and (in // production binaries) never destroyed, resulting in a memory leak. This // will be the case until we implement safe unpatching of a method. // However, it is quite difficult to unpatch a method (because other // threads in the process may be using it) so we are leaving it for now. // See however UnsafeUnpatch, which can be used for binaries where you // know only one thread is running, e.g. unit tests. static SideStepError RawPatch(void* target_function, void* replacement_function, void** original_function_stub); // Unpatches target_function and deletes the stub that previously could be // used to call the original version of the function. // // DELETES the stub that is passed to the function. // // @param target_function Pointer to the target function which was // previously patched, i.e. a pointer which value should match the value // of the symbol prior to patching it. // // @param replacement_function Pointer to the function target_function // was patched to. // // @param original_function_stub Pointer to the stub returned when // patching, that could be used to call the original version of the // patched function. This function will also delete the stub, which after // unpatching is useless. // // If your original call was // Patch(VirtualAlloc, MyVirtualAlloc, &origptr) // then to undo it you would call // Unpatch(VirtualAlloc, MyVirtualAlloc, origptr); // // @return One of the EnSideStepError error codes; only SIDESTEP_SUCCESS // indicates success. static SideStepError Unpatch(void* target_function, void* replacement_function, void* original_function_stub); // A helper routine when patching, which follows jmp instructions at // function addresses, to get to the "actual" function contents. // This allows us to identify two functions that are at different // addresses but actually resolve to the same code. // // @param target_function Pointer to a function. // // @return Either target_function (the input parameter), or if // target_function's body consists entirely of a JMP instruction, // the address it JMPs to (or more precisely, the address at the end // of a chain of JMPs). template <class T> static T ResolveTarget(T target_function) { return (T)ResolveTargetImpl((unsigned char*)target_function, NULL); } // Allocates a block of memory of size MAX_PREAMBLE_STUB_SIZE that is as // close (within 2GB) as possible to target. This is done to ensure that // we can perform a relative jump from target to a trampoline if the // replacement function is > +-2GB from target. This means that we only need // to patch 5 bytes in the target function. // // @param target Pointer to target function. // // @return Returns a block of memory of size MAX_PREAMBLE_STUB_SIZE that can // be used to store a function preamble block. static unsigned char* AllocPreambleBlockNear(void* target); // Frees a block allocated by AllocPreambleBlockNear. // // @param block Block that was returned by AllocPreambleBlockNear. static void FreePreambleBlock(unsigned char* block); private: friend class DeleteUnsignedCharArray; // Used to store data allocated for preamble stubs struct PreamblePage { unsigned int magic_; PreamblePage* next_; // This member points to a linked list of free blocks within the page // or NULL if at the end void* free_; }; // In 64-bit mode, the replacement function must be within 2GB of the original // target in order to only require 5 bytes for the function patch. To meet // this requirement we're creating an allocator within this class to // allocate blocks that are within 2GB of a given target. This member is the // head of a linked list of pages used to allocate blocks that are within // 2GB of the target. static PreamblePage* preamble_pages_; // Page granularity static long granularity_; // Page size static long pagesize_; // Determines if the patcher has been initialized. static bool initialized_; // Used to initialize static members. static void Initialize(); // Patches a function by overwriting its first few bytes with // a jump to a different function. This is similar to the RawPatch // function except that it uses the stub allocated by the caller // instead of allocating it. // // We call VirtualProtect to make the // target function writable at least for the duration of the call. // // @param target_function A pointer to the function that should be // patched. // // @param replacement_function A pointer to the function that should // replace the target function. The replacement function must have // exactly the same calling convention and parameters as the original // function. // // @param preamble_stub A pointer to a buffer where the preamble stub // should be copied. The size of the buffer should be sufficient to // hold the preamble bytes. // // @param stub_size Size in bytes of the buffer allocated for the // preamble_stub // // @param bytes_needed Pointer to a variable that receives the minimum // number of bytes required for the stub. Can be set to NULL if you're // not interested. // // @return An error code indicating the result of patching. static SideStepError RawPatchWithStubAndProtections( void* target_function, void* replacement_function, unsigned char* preamble_stub, unsigned long stub_size, unsigned long* bytes_needed); // A helper function used by RawPatchWithStubAndProtections -- it // does everything but the VirtualProtect work. Defined in // preamble_patcher_with_stub.cc. // // @param target_function A pointer to the function that should be // patched. // // @param replacement_function A pointer to the function that should // replace the target function. The replacement function must have // exactly the same calling convention and parameters as the original // function. // // @param preamble_stub A pointer to a buffer where the preamble stub // should be copied. The size of the buffer should be sufficient to // hold the preamble bytes. // // @param stub_size Size in bytes of the buffer allocated for the // preamble_stub // // @param bytes_needed Pointer to a variable that receives the minimum // number of bytes required for the stub. Can be set to NULL if you're // not interested. // // @return An error code indicating the result of patching. static SideStepError RawPatchWithStub(void* target_function, void* replacement_function, unsigned char* preamble_stub, unsigned long stub_size, unsigned long* bytes_needed); // A helper routine when patching, which follows jmp instructions at // function addresses, to get to the "actual" function contents. // This allows us to identify two functions that are at different // addresses but actually resolve to the same code. // // @param target_function Pointer to a function. // // @param stop_before If, when following JMP instructions from // target_function, we get to the address stop, we return // immediately, the address that jumps to stop_before. // // @param stop_before_trampoline When following JMP instructions from // target_function, stop before a trampoline is detected. See comment in // PreamblePatcher::RawPatchWithStub for more information. This parameter // has no effect in 32-bit mode. // // @return Either target_function (the input parameter), or if // target_function's body consists entirely of a JMP instruction, // the address it JMPs to (or more precisely, the address at the end // of a chain of JMPs). static void* ResolveTargetImpl(unsigned char* target_function, unsigned char* stop_before, bool stop_before_trampoline = false); // Helper routine that attempts to allocate a page as close (within 2GB) // as possible to target. // // @param target Pointer to target function. // // @return Returns an address that is within 2GB of target. static void* AllocPageNear(void* target); // Helper routine that determines if a target instruction is a short // conditional jump. // // @param target Pointer to instruction. // // @param instruction_size Size of the instruction in bytes. // // @return Returns true if the instruction is a short conditional jump. static bool IsShortConditionalJump(unsigned char* target, unsigned int instruction_size); // Helper routine that determines if a target instruction is a near // conditional jump. // // @param target Pointer to instruction. // // @param instruction_size Size of the instruction in bytes. // // @return Returns true if the instruction is a near conditional jump. static bool IsNearConditionalJump(unsigned char* target, unsigned int instruction_size); // Helper routine that determines if a target instruction is a near // relative jump. // // @param target Pointer to instruction. // // @param instruction_size Size of the instruction in bytes. // // @return Returns true if the instruction is a near absolute jump. static bool IsNearRelativeJump(unsigned char* target, unsigned int instruction_size); // Helper routine that determines if a target instruction is a near // absolute call. // // @param target Pointer to instruction. // // @param instruction_size Size of the instruction in bytes. // // @return Returns true if the instruction is a near absolute call. static bool IsNearAbsoluteCall(unsigned char* target, unsigned int instruction_size); // Helper routine that determines if a target instruction is a near // absolute call. // // @param target Pointer to instruction. // // @param instruction_size Size of the instruction in bytes. // // @return Returns true if the instruction is a near absolute call. static bool IsNearRelativeCall(unsigned char* target, unsigned int instruction_size); // Helper routine that determines if a target instruction is a 64-bit MOV // that uses a RIP-relative displacement. // // @param target Pointer to instruction. // // @param instruction_size Size of the instruction in bytes. // // @return Returns true if the instruction is a MOV with displacement. static bool IsMovWithDisplacement(unsigned char* target, unsigned int instruction_size); // Helper routine that converts a short conditional jump instruction // to a near conditional jump in a target buffer. Note that the target // buffer must be within 2GB of the source for the near jump to work. // // A short conditional jump instruction is in the format: // 7x xx = Jcc rel8off // // @param source Pointer to instruction. // // @param instruction_size Size of the instruction. // // @param target Target buffer to write the new instruction. // // @param target_bytes Pointer to a buffer that contains the size // of the target instruction, in bytes. // // @param target_size Size of the target buffer. // // @return Returns SIDESTEP_SUCCESS if successful, otherwise an error. static SideStepError PatchShortConditionalJump(unsigned char* source, unsigned int instruction_size, unsigned char* target, unsigned int* target_bytes, unsigned int target_size); // Helper routine that converts an instruction that will convert various // jump-like instructions to corresponding instructions in the target buffer. // What this routine does is fix up the relative offsets contained in jump // instructions to point back to the original target routine. Like with // PatchShortConditionalJump, the target buffer must be within 2GB of the // source. // // We currently handle the following instructions: // // E9 xx xx xx xx = JMP rel32off // 0F 8x xx xx xx xx = Jcc rel32off // FF /2 xx xx xx xx = CALL reg/mem32/mem64 // E8 xx xx xx xx = CALL rel32off // // It should not be hard to update this function to support other // instructions that jump to relative targets. // // @param source Pointer to instruction. // // @param instruction_size Size of the instruction. // // @param target Target buffer to write the new instruction. // // @param target_bytes Pointer to a buffer that contains the size // of the target instruction, in bytes. // // @param target_size Size of the target buffer. // // @return Returns SIDESTEP_SUCCESS if successful, otherwise an error. static SideStepError PatchNearJumpOrCall(unsigned char* source, unsigned int instruction_size, unsigned char* target, unsigned int* target_bytes, unsigned int target_size); // Helper routine that patches a 64-bit MOV instruction with a RIP-relative // displacement. The target buffer must be within 2GB of the source. // // 48 8B 0D XX XX XX XX = MOV rel32off // // @param source Pointer to instruction. // // @param instruction_size Size of the instruction. // // @param target Target buffer to write the new instruction. // // @param target_bytes Pointer to a buffer that contains the size // of the target instruction, in bytes. // // @param target_size Size of the target buffer. // // @return Returns SIDESTEP_SUCCESS if successful, otherwise an error. static SideStepError PatchMovWithDisplacement(unsigned char* source, unsigned int instruction_size, unsigned char* target, unsigned int* target_bytes, unsigned int target_size); }; }; // namespace sidestep #endif // GOOGLE_PERFTOOLS_PREAMBLE_PATCHER_H_