docs: switch Chinese comments to English comments and add jni_trace comments

Author: sanfengAndroid

fakelinker-test/src/main/cpp/test/test_fakelinker.cpp

@@ -224,7 +224,7 @@ TEST(FakeLinker, namespaceTest) {
   EXPECT_EQ(g_fakelinker_export.android_namespace_add_ld_library_path(thiz_np, "/data/local/add_ld_library"),
             FakeLinkerError::kErrorNo)
     << "android_namespace_add_ld_library_path";
-  // 目前还不能修改 default_library 和 permitted_library
+  // Currently unable to modify default_library and permitted_library
   EXPECT_EQ(g_fakelinker_export.android_namespace_add_default_library_path(thiz_np, "data/local/add_default_library"),
             FakeLinkerError::kErrorUnavailable)
     << "android_namespace_add_default_library_path";

library/src/main/cpp/common/maps_util.cpp

@@ -66,9 +66,9 @@ bool MapsHelper::ReadLibraryMap() {
     } else if (!FormatLine()) {
       break;
     }
-    // 库映射可能是不连续的, 但不会出现交叉
+    // Library mapping may be discontinuous, but there will be no crossing
     if (found_inode != inode_ && inode_ != 0) {
-      // 严格判断库是否正确, 一个库至少有读执行内存段
+      // Strictly check if library is correct, a library must have at least read-execute memory segment
       if ((protect & (kMPRead | kMPExecute)) == (kMPRead | kMPExecute)) {
         break;
       } else {
@@ -91,7 +91,7 @@ bool MapsHelper::ReadLibraryMap() {
     page_.push_back(page);
   }
   if (page_.empty()) {
-    // 文件已读取完
+    // File has been read completely
     return true;
   }
   return VerifyLibraryMap();
@@ -300,9 +300,9 @@ bool MapsHelper::FormatLine() {
   if (num == 5) {
     path_[0] = '\0';
   }
-  // 验证权限字符串是否有效
+  // Verify if permission string is valid
   if (FormatProtect() == kMPInvalid) {
-    // 由于maps文件常常改变,有可能读取到无效类型
+    // Since maps file changes frequently, invalid types may be read
     return false;
   }
   return num == 6 || num == 5;
@@ -371,12 +371,12 @@ bool MapsHelper::MakeLibraryName(const char *library_name) {
 }
 
 /**
- * @brief 验证一个库的有效映射是包含 可执行段
+ * @brief Verify that a library's valid mapping contains executable segments
  *
  */
 bool MapsHelper::VerifyLibraryMap() {
   for (auto &page : page_) {
-    // 模拟器下查找arm库没有可执行权限
+    // ARM libraries found under emulator have no executable permissions
     if ((page.old_protect & (kMPExecute | kMPWrite)) != 0) {
       return true;
     }

library/src/main/cpp/include/fakelinker/art_symbol.h

@@ -45,7 +45,7 @@ class DamagedRuntime {
   ANDROID_GE_R std::unique_ptr<void *> jni_id_manager_;
   std::unique_ptr<JavaVMExt> java_vm_;
 
-  // 在 Runtime 类中的偏移,使用前应设置
+  // Offset in Runtime class, should be set before use
   static size_t jvm_offset_;
 };
 

library/src/main/cpp/include/fakelinker/elf_reader.h

@@ -25,8 +25,8 @@ class MapsHelper;
 
 struct ElfDiskInfo {
   Address section_strtab_offset;
-  Address section_strtab_addr = 0; // 实际内存中的地址
-  uintptr_t section_strtab_size;   // 节区大小
+  Address section_strtab_addr = 0; // Actual address in memory
+  uintptr_t section_strtab_size;   // Section size
   uintptr_t str_addralign;
 
   Address section_symtab_offset;
@@ -60,7 +60,7 @@ class ElfReader {
   bool Load(address_space_params *address_space);
   bool LoadFromMemory(const char *name);
   bool LoadFromDisk(const char *library_name);
-  // 缓存内部符号,加速查找
+  // Cache internal symbols to accelerate lookup
   bool CacheInternalSymbols();
   bool DecompressDebugData();
 
@@ -103,12 +103,15 @@ class ElfReader {
   uint64_t FindInternalSymbolByPrefix(std::string_view prefix);
 
   /**
-   * 查找内部符号地址,可支持正则表达式,正则表达式使用默认 std::regex 因此需要调用者保证正则表达式合法,
-   * 注意: 虽然支持正则表达式但也优先匹配符号名称,这是方便完全符号匹配与正则匹配一起查找,避免多次遍历符号表
+   * Find internal symbol addresses, supports regular expressions. Regular expressions use default std::regex
+   * so callers must ensure regex expressions are valid.
+   * Note: Although regex is supported, symbol names are matched first for convenience of exact symbol
+   * matching and regex matching together, avoiding multiple traversals of the symbol table.
    *
-   * @param symbols  查找的内部符号名称或正则表达式集合,保证非空避免查找整个符号表
-   * @param useRegex 开启正则匹配支持
-   * @return         返回地址集合,找到则对应地址非0
+   * @param symbols  Collection of internal symbol names or regex expressions to find, ensure non-empty to avoid
+   * searching entire symbol table
+   * @param useRegex Enable regex matching support
+   * @return         Return address collection, found addresses are non-zero
    */
   std::vector<Address> FindInternalSymbols(const std::vector<std::string> &symbols, bool useRegex = false);
 
@@ -175,7 +178,7 @@ class ElfReader {
   // Size in bytes of the gap mapping.
   size_t gap_size_;
   // Load bias.
-  // 库加载基址,通常就是 load_start_ 因为第一个页通常虚拟地址为0
+  // Library load base address, usually same as load_start_ because first page typically has virtual address 0
   ElfW(Addr) load_bias_;
 
   // Loaded phdr.

library/src/main/cpp/include/fakelinker/fake_linker.h

@@ -136,7 +136,7 @@ typedef void *(*DlsymFun)(void *handle, const char *symbol_name, void *caller_ad
 
 ANDROID_GE_N enum NamespaceFindType {
   kNPOriginal,      /**< It is already a namespace, do not query */
-  kNPSoinfo,        /**< Specifiy the namespace in which soinfo looks for it */
+  kNPSoinfo,        /**< Specify the namespace in which soinfo looks for it */
   kNPNamespaceName, /**< Find the namespace with the specified name */
 };
 

library/src/main/cpp/include/fakelinker/maps_util.h

@@ -26,7 +26,7 @@ enum MapsProt {
   kMPRead = PROT_READ,
   kMPWrite = PROT_WRITE,
   kMPExecute = PROT_EXEC,
-  // 与 mman.h 中不同
+  // Different from mman.h
   kMPShared = 8,
   kMPPrivate = 16,
   kMPReadWrite = kMPRead | kMPWrite,

library/src/main/cpp/include/fakelinker/symbol_resolver.h

@@ -8,13 +8,13 @@ namespace fakelinker {
 class SymbolResolver {
 public:
   struct SymbolResult {
-    // 解析的库/地方范围的起始地址
+    // Start address of the resolved library/location range
     uintptr_t start;
-    // 解析的库/地方范围的结束地址
+    // End address of the resolved library/location range
     uintptr_t end;
-    // 当前地址相对于 start 的偏移
+    // Offset of the current address relative to start
     uintptr_t offset = UINTPTR_MAX;
-    // 库名称
+    // Library name
     const char *name;
   };
 
@@ -23,26 +23,26 @@ class SymbolResolver {
   bool AddAddressRange(const std::string &name, uintptr_t start, uintptr_t end);
 
   /**
-   * @brief 格式化地址如下:
-   *         head 地址 [库名!偏移]
+   * @brief Format address as follows:
+   *         head address [library_name!offset]
    *
-   * @param  address        待格式化地址
-   * @param  default_format 如果不再监控范围内是否格式化为 head 地址
-   * @param  head           添加指定头
+   * @param  address        Address to be formatted
+   * @param  default_format Whether to format as head address if not in monitoring range
+   * @param  head           Add specified header
    * @return std::string
    */
   std::string FormatAddress(uintptr_t address, bool default_format, const std::string &head = "");
 
   /**
-   * @brief 指定buffer处格式化地址,避免内存拷贝
+   * @brief Format address at specified buffer location to avoid memory copying
    *
-   * @param  buffer         指定缓冲区
-   * @param  max_length     最大缓冲区大小
-   * @param  address        待格式化的地址
-   * @param  default_format 如果不再监控范围内是否格式化为 head 地址
-   * @param  head           添加指定头
-   * @return true           在地址范围内
-   * @return false          不在地址范围内
+   * @param  buffer         Specify the buffer to be written, which will be updated after writing
+   * @param  max_length     Maximum buffer size
+   * @param  address        Address to be formatted
+   * @param  default_format Whether to format as head address if not in monitoring range
+   * @param  head           Add specified header
+   * @return true           Within address range
+   * @return false          Not within address range
    */
   bool FormatAddressFromBuffer(char *&buffer, size_t max_length, uintptr_t address, bool default_format,
                                const std::string &head = "");

library/src/main/cpp/include/fakelinker/trace_jni.h

@@ -30,17 +30,37 @@ struct _is_valid_container<
     : std::is_same<typename T::value_type, size_t> {};
 
 
+/**
+ * @struct TraceInvokeContext
+ * @brief Context structure for tracing JNI method invocations.
+ *
+ * This structure holds information relevant to a JNI method invocation trace,
+ * including the JNI environment, caller address, result type, method ID (for
+ * varargs), and a message buffer for logging or debugging purposes.
+ *
+ * Members:
+ * - env: Pointer to the JNI environment associated with the current thread.
+ * - caller: Address of the entity invoking the JNI method.
+ * - result: The result type of the JNI call, if applicable.
+ * - method: The JNI method ID, used when the method has variable arguments.
+ * - message: Buffer to store trace or debug messages (up to 4096 characters).
+ * - message_length: The current length of the message stored in the buffer.
+ *
+ * Constructor:
+ * - Initializes the context with the given result type, JNI environment, and caller address.
+ *   The method ID is initialized to nullptr.
+ */
 template <typename jtype, bool AllowAccessArgs = true>
 struct TraceInvokeContext {
-  // JNIEnv 对象
+  // JNIEnv object pointer, note: it contains function pointers after our Hook
   JNIEnv *env;
-  // 调用者的地址
+  // Caller's address
   void *caller;
-  // 如果有返回值,则是
+  // JNI call return value
   jtype result;
-  // 当有可变参数 va_list 时则为具体的方法
+  // Specific method when there are variable arguments va_list
   jmethodID method;
-  // 保存消息
+  // Store messages
   char message[4096];
   uint32_t message_length = 0;
 
@@ -50,9 +70,9 @@ struct TraceInvokeContext {
 
 template <>
 struct TraceInvokeContext<void, true> {
-  // JNIEnv 对象
+  // JNIEnv object pointer, note: it contains function pointers after our Hook
   JNIEnv *env;
-  // 调用者的地址
+  // Caller's address
   void *caller;
   jmethodID method;
   char message[4096];
@@ -81,7 +101,7 @@ template <typename Derived>
 class BaseTraceJNICallback;
 
 namespace jni_trace {
-// 直接申明全局变量避免增加寻址操作
+// Directly declare global variables to avoid adding addressing operations
 extern JNINativeInterface backup_jni;
 extern JNINativeInterface *org_jni;
 extern JNINativeInterface hook_jni;
@@ -1160,7 +1180,63 @@ class JNIMonitor {
   DISALLOW_COPY_AND_ASSIGN(JNIMonitor);
 };
 
-
+/**
+ * @class BaseTraceJNICallback
+ * @brief A base class for tracing and logging JNI calls in a custom JNIEnv wrapper.
+ *
+ * This template class provides a comprehensive framework for intercepting, tracing, and logging
+ * JNI function calls. It is designed to be inherited by user-defined callback classes, such as
+ * DefaultTraceJNICallback, to customize tracing behavior for JNI environments.
+ *
+ * @tparam Derived The derived callback class implementing custom trace logic.
+ *
+ * ## Features
+ * - Intercepts all major JNI function calls, including method/field access, object creation, array operations, etc.
+ * - Formats and logs method/field IDs, arguments, return values, and JNI object types.
+ * - Supports strict mode for enhanced safety and validation.
+ * - Maintains caches for method and field descriptions to improve performance.
+ * - Provides utilities for formatting JNI types, classes, strings, and objects.
+ * - Integrates with Android logging via __android_log_print.
+ * - Supports registration of trace hooks for a wide range of JNI functions.
+ * - Allows derived classes to override trace formatting and logging behavior.
+ *
+ * ## Usage
+ * 1. Inherit from BaseTraceJNICallback in your callback class:
+ *    @code
+ *    class DefaultTraceJNICallback : public BaseTraceJNICallback<DefaultTraceJNICallback> {
+ *    public:
+ *      explicit DefaultTraceJNICallback(bool strict) : BaseTraceJNICallback(strict) {}
+ *    };
+ *    @endcode
+ *
+ * 2. Instantiate your callback and initialize tracing:
+ *    @code
+ *    DefaultTraceJNICallback tracer(true);
+ *    tracer.InitTrace(env); // env is a pointer to JNIEnv
+ *    tracer->AddMonitorAddress(0x1000, 0x2000); // Add address to monitor
+ *    tracer->AddLibraryMonitor("libexample.so", false); // Add library to monitor
+ *    tracer.DefaultRegister(); // Registers default JNI functions and start tracing
+ *    @endcode
+ *
+ * 3. Optionally, use SetStrictMode, SetOriginalEnv, or ClearCache as needed.
+ *
+ * ## Important Methods
+ * - InitTrace(JNIEnv* env): Initializes tracing and hooks JNI functions.
+ * - DefaultRegister(): Registers a default set of JNI functions and start tracing.
+ * - FormatMethodID/FormatFieldID: Returns human-readable descriptions for method/field IDs.
+ * - FormatJNIArguments/FormatReturnValue: Formats and logs JNI call arguments and return values.
+ * - TraceLog/TraceLine: Logging utilities for trace output.
+ *
+ * ## Thread Safety
+ * JNI callbacks use independent Context instances to achieve thread safety, but
+ * JNIMonitor element addition is not thread-safe. It is recommended to complete
+ * adding monitoring addresses before starting the trace.
+ *
+ * ## Example
+ * See DefaultTraceJNICallback in default_trace_jni.h for a minimal implementation.
+ *
+ * @see DefaultTraceJNICallback
+ */
 template <typename Derived>
 class BaseTraceJNICallback : public HookJNIEnv<Derived> {
   friend class HookJNIEnv<Derived>;

library/src/main/cpp/linker/art/hook_jni_native_interface_impl.cpp

@@ -79,7 +79,7 @@ int HookJniNativeInterfaces(HookJniUnit *items, int len) {
     if (item->offset < min || item->offset > max || item->hook_method == nullptr) {
       continue;
     }
-    // 这里再判断下是否已经Hook,避免存在多次相同调用陷入死循环
+    // Check if the method is already hooked to prevent infinite loops from multiple identical calls
     target = reinterpret_cast<void **>((char *)original_functions + item->offset);
     if (*target == item->hook_method) {
       continue;
@@ -241,8 +241,9 @@ static void *GetOriginalNativeFunction(const uintptr_t *art_method) {
 }
 
 /*
- * 由于手动修改 jni入口点没有加锁,因此尽量做到每次读写
- * */
+ * Since manual modification of JNI entry points is not locked,
+ * try to achieve atomic read/write operations for each access.
+ */
 inline static uint32_t GetAccessFlags(const char *art_method) {
   return *reinterpret_cast<const uint32_t *>(art_method + access_flags_art_method_offset);
 }
@@ -270,7 +271,7 @@ inline static bool HasAccessFlag(char *art_method, uint32_t flag) {
 }
 
 inline static bool ClearFastNativeFlag(char *art_method) {
-  // Android 9.0以上没有判断 FastNative 标志
+  // Android 9.0+ does not check FastNative flag
   return api < __ANDROID_API_P__ && ClearAccessFlag(art_method, kAccFastNative);
 }
 
@@ -322,9 +323,10 @@ int HookJavaNativeFunctions(JNIEnv *env, jclass clazz, HookRegisterNativeUnit *i
     if (env->RegisterNatives(clazz, methods, 1) == JNI_OK) {
       success++;
       /*
-       * Android 8.0 ,8.1 必须清除 FastNative 标志才能注册成功,所以如果原来包含
-       * FastNative 标志还得恢复, 否者调用原方法可能会出现问题
-       * */
+       * Android 8.0, 8.1 must clear the FastNative flag to register successfully,
+       * so if it originally contained the FastNative flag, it must be restored,
+       * otherwise calling the original method may cause problems
+       */
       if (restore && (api == __ANDROID_API_O__ || api == __ANDROID_API_O_MR1__)) {
         AddAccessFlag(reinterpret_cast<char *>(artMethod), kAccFastNative);
       }