hook.h File Reference

Hook macros and typed hooks that wrap a recompiled function. More...

#include <atomic>
#include <cstring>
#include <format>
#include <tuple>
#include <type_traits>
#include <cstddef>
#include <string>
#include <utility>
#include <rex/memory/mapped_ptr.h>
#include <rex/platform.h>
#include <rex/logging/log_category.h>
#include <rex/ppc/context.h>
#include <rex/ppc/recompiled_code.h>
#include <rex/ppc/call.h>
#include <rex/types.h>
#include <rex/assert.h>
#include <rex/ppc/image.h>
#include <rex/utility.h>
#include <tracy/Tracy.hpp>

Go to the source code of this file.

Classes
struct	rex::ppc::DetourOriginal< R(Args...)>
struct	rex::ppc::DetourOriginal< R(PPCContext &, Args...)>

Namespaces
namespace	rex
namespace	rex::ppc

Macros
#define	REX_HOOK(subroutine, function)
#define	REX_HOOK_RAW(name)
#define	REX_STUB(subroutine)
#define	REX_STUB_LOG(subroutine, msg)
#define	REX_STUB_RETURN(subroutine, value)
#define	REX_EXPORT(name, function)
#define	REX_EXPORT_STUB(name)
#define	REX_EXPORT_STUB_RETURN(name, value)
#define	REX_IMPORT(symbol, callable, sig)
#define	REX_DETOUR(name, Ret, params)

Functions
template<auto Body>
void	rex::ppc::RunDetour (PPCContext &ctx, u8 *base, const char *name, PPCFunc *host)

Detailed Description

Hook macros and typed hooks that wrap a recompiled function.

Copyright

Copyright (c) 2026 Tom Clay tomc@.nosp@m.tcte.nosp@m.chstu.nosp@m.ff.c.nosp@m.om All rights reserved.

License

BSD 3-Clause License See LICENSE file in the project root for full license text.

Macro Definition Documentation

REX_DETOUR

#define REX_DETOUR	(		name,
			Ret,
			params )

Value:

REX_EXTERN(__imp__##name);                                                          \
struct name##_rex_detour {                                                          \
  static inline const rex::ppc::DetourOriginal<Ret params> original{__imp__##name}; \
  static Ret Body params;                                                           \
};                                                                                  \
REX_HOOK_RAW(name) {                                                                \
  REX_DETAIL_DETOUR_ZONE(name)                                                      \
  rex::ppc::RunDetour<&name##_rex_detour::Body>(ctx, base, #name, name);            \
}                                                                                   \
Ret name##_rex_detour::Body params

Defines a typed hook whose body reads the arguments as parameters and calls original(args...) on every path, or original(ctx, args...) when the first parameter is PPCContext& ctx. No detour stays running across a guest SwitchToFiber, since the detour chain is thread local.

Parameters

name	The recompiled function symbol.
Ret	The return type, written to r3 or f1 for the caller.
params	The parameter list in parentheses, with names.

REX_DETOUR(ExampleFunction, u32, (u32 count)) {
  return original(count + 1) + 1;
}

REX_EXPORT

#define REX_EXPORT	(		name,
			function )

Value:

REX_HOOK(name, function)

Defines a hook whose symbol a kernel export table links against.

Parameters

name	The hook symbol.
function	The host function the hook wraps.

REX_EXPORT(__imp__CloseHandle, rex::xam::CloseHandle_shim)

REX_EXPORT_STUB

#define REX_EXPORT_STUB

(

name

)

Value:

REX_STUB(name)

Defines a stub whose symbol a kernel export table links against.

Parameters

name	The hook symbol.

REX_EXPORT_STUB(__imp__AniBlockOnAnimation);

REX_EXPORT_STUB_RETURN

#define REX_EXPORT_STUB_RETURN	(		name,
			value )

Value:

REX_STUB_RETURN(name, value)

Defines a stub that returns a fixed value and whose symbol a kernel export table links against.

Parameters

name	The hook symbol.
value	The value returned in r3.

REX_EXPORT_STUB_RETURN(__imp__DmRegisterCommandProcessorEx, 0);

REX_HOOK

#define REX_HOOK	(		subroutine,
			function )

Value:

extern "C" REX_DETAIL_ENTRY_EXPORT REX_FUNC(subroutine) {      \
  ZoneNamedN(___tracy_hook_zone, #subroutine, TracyIsStarted); \
  rex::ppc::GuestToHostThunk<function>(ctx, base);             \
}

Hooks a recompiled function with a native C++ function that takes plain types.

Parameters

subroutine	The recompiled function symbol.
function	The native function the hook calls.

REX_HOOK(ExampleFunction, ExampleHook);

REX_HOOK_RAW

#define REX_HOOK_RAW

(

name

)

Value:

extern "C" REX_DETAIL_ENTRY_EXPORT REX_FUNC(name)

Defines a raw hook with access to ctx and base.

Parameters

name	The recompiled function symbol.

REX_HOOK_RAW(ExampleFunction) {
  ctx.r3.u64 = 0;
}

REX_IMPORT

#define REX_IMPORT	(		symbol,
			callable,
			sig )

Value:

REX_EXTERN(symbol);                                              \
[[maybe_unused]] static rex::ppc::ImportFunction<sig> callable { \
  symbol                                                         \
}

Declares a typed callable import of a recompiled function, with internal linkage so it cannot collide with the generated weak alias on ELF.

Parameters

symbol	The exact linker symbol to reference.
callable	The name of the typed callable variable.
sig	The function signature, such as u32(u32, u32).

REX_IMPORT(ExampleFunction, example_function, u32(u32, u32));

REX_STUB

#define REX_STUB

(

subroutine

)

Value:

extern "C" REX_DETAIL_ENTRY_EXPORT REX_FUNC(subroutine) {                          \
  static constinit ::std::atomic_flag rex_stub_seen_;                              \
  ::rex::log::detail::WriteStub(::rex::log::cpu, rex_stub_seen_, #subroutine, {}); \
}

Defines a stub that logs a warning on the first call and at Dev level on later calls.

Parameters

subroutine

The recompiled function symbol.

REX_STUB(ExampleFunction);

REX_STUB_LOG

#define REX_STUB_LOG	(		subroutine,
			msg )

Value:

extern "C" REX_DETAIL_ENTRY_EXPORT REX_FUNC(subroutine) {                           \
  static constinit ::std::atomic_flag rex_stub_seen_;                               \
  ::rex::log::detail::WriteStub(::rex::log::cpu, rex_stub_seen_, #subroutine, msg); \
}

Defines a stub that logs a message on the first call and at Dev level on later calls.

Parameters

subroutine	The recompiled function symbol.
msg	The message logged with the stub.

REX_STUB_LOG(ExampleFunction, "skips the save");

REX_STUB_RETURN

#define REX_STUB_RETURN	(		subroutine,
			value )

Value:

extern "C" REX_DETAIL_ENTRY_EXPORT REX_FUNC(subroutine) {                          \
  static constinit ::std::atomic_flag rex_stub_seen_;                              \
  const auto rex_stub_value_ = (value);                                            \
  ::rex::log::detail::WriteStub(                                                   \
      ::rex::log::cpu, rex_stub_seen_, #subroutine,                                \
      ::std::format("returning {:#x}", static_cast<::rex::u32>(rex_stub_value_))); \
  ctx.r3.u64 = rex_stub_value_;                                                    \
}

Defines a stub that returns a fixed value in r3 and logs it like REX_STUB.

Parameters

subroutine	The recompiled function symbol.
value	The value returned in r3.

REX_STUB_RETURN(ExampleFunction, 0);