improve comments

4 files changed, 101 insertions, 63 deletions

diff --git a/core/src/xmake/binutils/elf/deplibs.c b/core/src/xmake/binutils/elf/deplibs.c
index b732efa7d..5288e2b1f 100644
--- a/core/src/xmake/binutils/elf/deplibs.c
+++ b/core/src/xmake/binutils/elf/deplibs.c
@@ -121,42 +121,27 @@ static tb_bool_t xm_binutils_elf_deplibs_32(tb_stream_ref_t istream, tb_hize_t b
 
     // read ELF header
     xm_elf32_header_t header;
-    if (!tb_stream_seek(istream, base_offset)) {
-        return tb_false;
-    }
-    if (!tb_stream_bread(istream, (tb_byte_t*)&header, sizeof(header))) {
+    if (!xm_binutils_elf_read_header_32(istream, base_offset, &header)) {
         return tb_false;
     }
 
+    // find program interpreter (PT_INTERP) and push
+    tb_char_t name[256];
     tb_size_t result_count = 0;
-
-    // find program interpreter (PT_INTERP)
-    if (header.e_phoff != 0 && header.e_phnum > 0) {
-        if (tb_stream_seek(istream, base_offset + header.e_phoff)) {
-            for (tb_uint16_t i = 0; i < header.e_phnum; i++) {
-                xm_elf32_phdr_t phdr;
-                if (!tb_stream_bread(istream, (tb_byte_t*)&phdr, sizeof(phdr))) {
-                    break;
-                }
-                if (phdr.p_type == XM_ELF_PT_INTERP) {
-                    tb_char_t name[256];
-                    if (xm_binutils_read_string(istream, base_offset + phdr.p_offset, name, sizeof(name)) && name[0]) {
-                        lua_pushinteger(lua, result_count + 1);
-                        lua_pushstring(lua, name);
-                        lua_settable(lua, -3);
-                        result_count++;
-                    }
-                    break;
-                }
-            }
-        }
+    if (xm_binutils_elf_find_interp_32(istream, base_offset, &header, name, sizeof(name))) {
+        lua_pushinteger(lua, result_count + 1);
+        lua_pushstring(lua, name);
+        lua_settable(lua, -3);
+        result_count++;
     }
 
+    // build dynamic/string table context
     xm_elf_context_t ctx;
     if (!xm_binutils_elf_get_context_32(istream, base_offset, &ctx)) {
         return tb_true;
     }
 
+    // scan .dynamic entries: collect NEEDED and read RPATH/RUNPATH
     tb_uint32_t count = (tb_uint32_t)(ctx.dynamic_size / sizeof(xm_elf32_dynamic_t));
     if (!tb_stream_seek(istream, base_offset + ctx.dynamic_offset)) {
         return tb_false;
@@ -194,6 +179,7 @@ static tb_bool_t xm_binutils_elf_deplibs_32(tb_stream_ref_t istream, tb_hize_t b
             tb_path_directory(binary_path, binary_dir, sizeof(binary_dir));
         }
 
+        // resolve $ORIGIN and rpath/runpath, push full paths
         tb_for_all (tb_char_t const*, name, needed_libs) {
             tb_char_t fullpath[TB_PATH_MAXN];
             xm_binutils_elf_resolve_path(name, runpath[0]? runpath : rpath, binary_dir[0]? binary_dir : tb_null, fullpath, sizeof(fullpath));
@@ -213,37 +199,21 @@ static tb_bool_t xm_binutils_elf_deplibs_64(tb_stream_ref_t istream, tb_hize_t b
 
     // read ELF header
     xm_elf64_header_t header;
-    if (!tb_stream_seek(istream, base_offset)) {
-        return tb_false;
-    }
-    if (!tb_stream_bread(istream, (tb_byte_t*)&header, sizeof(header))) {
+    if (!xm_binutils_elf_read_header_64(istream, base_offset, &header)) {
         return tb_false;
     }
 
+    // find program interpreter (PT_INTERP) and push
+    tb_char_t name[256];
     tb_size_t result_count = 0;
-
-    // find program interpreter (PT_INTERP)
-    if (header.e_phoff != 0 && header.e_phnum > 0) {
-        if (tb_stream_seek(istream, base_offset + header.e_phoff)) {
-            for (tb_uint16_t i = 0; i < header.e_phnum; i++) {
-                xm_elf64_phdr_t phdr;
-                if (!tb_stream_bread(istream, (tb_byte_t*)&phdr, sizeof(phdr))) {
-                    break;
-                }
-                if (phdr.p_type == XM_ELF_PT_INTERP) {
-                    tb_char_t name[256];
-                    if (xm_binutils_read_string(istream, base_offset + phdr.p_offset, name, sizeof(name)) && name[0]) {
-                        lua_pushinteger(lua, result_count + 1);
-                        lua_pushstring(lua, name);
-                        lua_settable(lua, -3);
-                        result_count++;
-                    }
-                    break;
-                }
-            }
-        }
+    if (xm_binutils_elf_find_interp_64(istream, base_offset, &header, name, sizeof(name))) {
+        lua_pushinteger(lua, result_count + 1);
+        lua_pushstring(lua, name);
+        lua_settable(lua, -3);
+        result_count++;
     }
 
+    // build dynamic/string table context
     xm_elf_context_t ctx;
     if (!xm_binutils_elf_get_context_64(istream, base_offset, &ctx)) {
         return tb_true;
diff --git a/core/src/xmake/binutils/elf/prefix.h b/core/src/xmake/binutils/elf/prefix.h
index c807acce6..d73609dfe 100644
--- a/core/src/xmake/binutils/elf/prefix.h
+++ b/core/src/xmake/binutils/elf/prefix.h
@@ -81,14 +81,14 @@
  */
 #include "tbox/prefix/packed.h"
 typedef struct __xm_elf_context_t {
-    tb_hize_t dynamic_offset;
-    tb_hize_t dynamic_size;
-    tb_hize_t strtab_offset;
-    tb_hize_t strtab_size;
-    tb_hize_t symtab_offset;
-    tb_hize_t symtab_size;
-    tb_hize_t symstr_offset;
-    tb_hize_t symstr_size;
+    tb_hize_t dynamic_offset; // file offset of .dynamic
+    tb_hize_t dynamic_size;   // size of .dynamic
+    tb_hize_t strtab_offset;  // file offset of .dynstr
+    tb_hize_t strtab_size;    // size of .dynstr
+    tb_hize_t symtab_offset;  // file offset of .symtab
+    tb_hize_t symtab_size;    // size of .symtab
+    tb_hize_t symstr_offset;  // file offset of .strtab (for .symtab)
+    tb_hize_t symstr_size;    // size of .strtab (for .symtab)
     tb_bool_t is64;
 } xm_elf_context_t;
 
@@ -518,4 +518,50 @@ static __tb_inline__ tb_bool_t xm_binutils_elf_get_context_64(tb_stream_ref_t is
     return (ctx->dynamic_offset != 0 && ctx->strtab_offset != 0);
 }
 
+// read ELF header (32-bit)
+static __tb_inline__ tb_bool_t xm_binutils_elf_read_header_32(tb_stream_ref_t istream, tb_hize_t base_offset, xm_elf32_header_t* header) {
+    if (!tb_stream_seek(istream, base_offset)) return tb_false;
+    if (!tb_stream_bread(istream, (tb_byte_t*)header, sizeof(*header))) return tb_false;
+    return tb_true;
+}
+
+// read ELF header (64-bit)
+static __tb_inline__ tb_bool_t xm_binutils_elf_read_header_64(tb_stream_ref_t istream, tb_hize_t base_offset, xm_elf64_header_t* header) {
+    if (!tb_stream_seek(istream, base_offset)) return tb_false;
+    if (!tb_stream_bread(istream, (tb_byte_t*)header, sizeof(*header))) return tb_false;
+    return tb_true;
+}
+
+// find PT_INTERP and read interpreter path (32-bit)
+static __tb_inline__ tb_bool_t xm_binutils_elf_find_interp_32(tb_stream_ref_t istream, tb_hize_t base_offset, xm_elf32_header_t const* header, tb_char_t* name, tb_size_t size) {
+    if (header->e_phoff != 0 && header->e_phnum > 0) {
+        if (tb_stream_seek(istream, base_offset + header->e_phoff)) {
+            for (tb_uint16_t i = 0; i < header->e_phnum; i++) {
+                xm_elf32_phdr_t phdr;
+                if (!tb_stream_bread(istream, (tb_byte_t*)&phdr, sizeof(phdr))) break;
+                if (phdr.p_type == XM_ELF_PT_INTERP) {
+                    return xm_binutils_read_string(istream, base_offset + phdr.p_offset, name, size) && name[0];
+                }
+            }
+        }
+    }
+    return tb_false;
+}
+
+// find PT_INTERP and read interpreter path (64-bit)
+static __tb_inline__ tb_bool_t xm_binutils_elf_find_interp_64(tb_stream_ref_t istream, tb_hize_t base_offset, xm_elf64_header_t const* header, tb_char_t* name, tb_size_t size) {
+    if (header->e_phoff != 0 && header->e_phnum > 0) {
+        if (tb_stream_seek(istream, base_offset + header->e_phoff)) {
+            for (tb_uint16_t i = 0; i < header->e_phnum; i++) {
+                xm_elf64_phdr_t phdr;
+                if (!tb_stream_bread(istream, (tb_byte_t*)&phdr, sizeof(phdr))) break;
+                if (phdr.p_type == XM_ELF_PT_INTERP) {
+                    return xm_binutils_read_string(istream, base_offset + phdr.p_offset, name, size) && name[0];
+                }
+            }
+        }
+    }
+    return tb_false;
+}
+
 #endif
diff --git a/core/src/xmake/binutils/elf/readsyms.c b/core/src/xmake/binutils/elf/readsyms.c
index 39c2ee0ab..200b7ffcb 100644
--- a/core/src/xmake/binutils/elf/readsyms.c
+++ b/core/src/xmake/binutils/elf/readsyms.c
@@ -37,16 +37,20 @@
 tb_bool_t xm_binutils_elf_read_symbols_32(tb_stream_ref_t istream, tb_hize_t base_offset, lua_State *lua) {
     tb_assert_and_check_return_val(istream && lua, tb_false);
 
+    // build context and ensure .symtab/.strtab are available
     xm_elf_context_t ctx;
     xm_binutils_elf_get_context_32(istream, base_offset, &ctx);
 
     if (!ctx.symtab_offset || !ctx.symstr_offset) {
+        // no symbol table present: return empty result
         lua_newtable(lua);
         return tb_true;
     }
 
+    // create result table
     lua_newtable(lua);
 
+    // compute symbol count and seek to .symtab
     tb_uint32_t sym_count = (tb_uint32_t)(ctx.symtab_size / sizeof(xm_elf32_symbol_t));
     if (!tb_stream_seek(istream, base_offset + ctx.symtab_offset)) {
         return tb_false;
@@ -59,20 +63,24 @@ tb_bool_t xm_binutils_elf_read_symbols_32(tb_stream_ref_t istream, tb_hize_t bas
             return tb_false;
         }
 
+        // skip NULL symbol entries
         if (sym.st_name == 0 && sym.st_value == 0 && sym.st_size == 0) {
             continue;
         }
 
+        // skip section/file symbols
         tb_uint8_t type = sym.st_info & 0xf;
         if (type == 3 || type == 4) {
             continue;
         }
 
+        // read symbol name from .strtab
         tb_char_t name[256];
         if (!xm_binutils_read_string(istream, base_offset + ctx.symstr_offset + sym.st_name, name, sizeof(name)) || !name[0]) {
             continue;
         }
 
+        // skip internal ('.', '$') and local-defined symbols
         if (name[0] == '.' || name[0] == '$') {
             continue;
         }
@@ -82,6 +90,7 @@ tb_bool_t xm_binutils_elf_read_symbols_32(tb_stream_ref_t istream, tb_hize_t bas
             continue;
         }
 
+        // push symbol entry: name + nm-style type
         lua_pushinteger(lua, result_count + 1);
         lua_newtable(lua);
 
@@ -105,16 +114,20 @@ tb_bool_t xm_binutils_elf_read_symbols_32(tb_stream_ref_t istream, tb_hize_t bas
 tb_bool_t xm_binutils_elf_read_symbols_64(tb_stream_ref_t istream, tb_hize_t base_offset, lua_State *lua) {
     tb_assert_and_check_return_val(istream && lua, tb_false);
 
+    // build context and ensure .symtab/.strtab are available
     xm_elf_context_t ctx;
     xm_binutils_elf_get_context_64(istream, base_offset, &ctx);
 
     if (!ctx.symtab_offset || !ctx.symstr_offset) {
+        // no symbol table present: return empty result
         lua_newtable(lua);
         return tb_true;
     }
 
+    // create result table
     lua_newtable(lua);
 
+    // compute symbol count and seek to .symtab
     tb_uint32_t sym_count = (tb_uint32_t)(ctx.symtab_size / sizeof(xm_elf64_symbol_t));
     if (!tb_stream_seek(istream, base_offset + ctx.symtab_offset)) {
         return tb_false;
@@ -127,20 +140,24 @@ tb_bool_t xm_binutils_elf_read_symbols_64(tb_stream_ref_t istream, tb_hize_t bas
             return tb_false;
         }
 
+        // skip NULL symbol entries
         if (sym.st_name == 0 && sym.st_value == 0 && sym.st_size == 0) {
             continue;
         }
 
+        // skip section/file symbols
         tb_uint8_t type = sym.st_info & 0xf;
         if (type == 3 || type == 4) {
             continue;
         }
 
+        // read symbol name from .strtab
         tb_char_t name[256];
         if (!xm_binutils_read_string(istream, base_offset + ctx.symstr_offset + sym.st_name, name, sizeof(name)) || !name[0]) {
             continue;
         }
 
+        // skip internal ('.', '$') and local-defined symbols
         if (name[0] == '.' || name[0] == '$') {
             continue;
         }
@@ -150,6 +167,7 @@ tb_bool_t xm_binutils_elf_read_symbols_64(tb_stream_ref_t istream, tb_hize_t bas
             continue;
         }
 
+        // push symbol entry: name + nm-style type
         lua_pushinteger(lua, result_count + 1);
         lua_newtable(lua);
 
@@ -202,4 +220,3 @@ tb_bool_t xm_binutils_elf_read_symbols(tb_stream_ref_t istream, tb_hize_t base_o
 
     return tb_false;
 }
-
diff --git a/core/src/xmake/binutils/elf/rpath.c b/core/src/xmake/binutils/elf/rpath.c
index c99c8c4ad..2614c4694 100644
--- a/core/src/xmake/binutils/elf/rpath.c
+++ b/core/src/xmake/binutils/elf/rpath.c
@@ -57,6 +57,7 @@ static tb_void_t xm_binutils_elf_add_rpaths(lua_State *lua, tb_char_t const* rpa
     }
 }
 
+// parse .dynamic section and read DT_RPATH/DT_RUNPATH to build rpath list
 static tb_bool_t xm_binutils_elf_rpath_list_impl(tb_stream_ref_t istream, tb_hize_t base_offset, xm_elf_context_t* ctx, lua_State *lua) {
     tb_bool_t ok = tb_false;
     do {
@@ -66,6 +67,7 @@ static tb_bool_t xm_binutils_elf_rpath_list_impl(tb_stream_ref_t istream, tb_hiz
         tb_char_t rpath[8192] = {0};
         tb_char_t runpath[8192] = {0};
 
+        // scan dynamic entries
         for (tb_uint32_t i = 0; i < count; i++) {
             tb_hize_t val = 0;
             tb_hize_t tag = 0;
@@ -83,6 +85,7 @@ static tb_bool_t xm_binutils_elf_rpath_list_impl(tb_stream_ref_t istream, tb_hiz
             }
 
             if (tag == XM_ELF_DT_NULL) break;
+            // read rpath/runpath string from strtab
             if (tag == XM_ELF_DT_RPATH) {
                  xm_binutils_read_string(istream, base_offset + ctx->strtab_offset + val, rpath, sizeof(rpath));
             } else if (tag == XM_ELF_DT_RUNPATH) {
@@ -90,6 +93,7 @@ static tb_bool_t xm_binutils_elf_rpath_list_impl(tb_stream_ref_t istream, tb_hiz
             }
         }
 
+        // split rpath(s) and push into Lua table
         tb_size_t result_count = 0;
         if (runpath[0]) {
             xm_binutils_elf_add_rpaths(lua, runpath, &result_count);
@@ -101,8 +105,7 @@ static tb_bool_t xm_binutils_elf_rpath_list_impl(tb_stream_ref_t istream, tb_hiz
     return ok;
 }
 
-
-
+// remove DT_RPATH/DT_RUNPATH entries from .dynamic and write back
 static tb_bool_t xm_binutils_elf_rpath_clean_impl(tb_stream_ref_t istream, tb_hize_t base_offset, xm_elf_context_t* ctx) {
     tb_bool_t ok = tb_false;
     tb_byte_t* buffer = tb_null;
@@ -117,6 +120,7 @@ static tb_bool_t xm_binutils_elf_rpath_clean_impl(tb_stream_ref_t istream, tb_hi
         if (!tb_stream_seek(istream, base_offset + ctx->dynamic_offset)) break;
         if (!tb_stream_bread(istream, buffer, dyn_size)) break;
 
+        // p: read pointer, w: write pointer after filtering
         tb_byte_t* p = buffer;
         tb_byte_t* w = buffer;
         tb_size_t entry_size = ctx->is64 ? sizeof(xm_elf64_dynamic_t) : sizeof(xm_elf32_dynamic_t);
@@ -137,6 +141,7 @@ static tb_bool_t xm_binutils_elf_rpath_clean_impl(tb_stream_ref_t istream, tb_hi
                 break;
             }
 
+            // keep entries except rpath/runpath
             if (tag != XM_ELF_DT_RPATH && tag != XM_ELF_DT_RUNPATH) {
                 if (w != p) tb_memcpy(w, p, entry_size);
                 w += entry_size;
@@ -174,6 +179,7 @@ tb_bool_t xm_binutils_elf_rpath_list(tb_stream_ref_t istream, tb_hize_t base_off
         if (!tb_stream_seek(istream, base_offset)) break;
         if (!tb_stream_bread(istream, ident, sizeof(ident))) break;
 
+        // build ELF context (dynamic, strtab offsets)
         xm_elf_context_t ctx;
         if (ident[XM_ELF_EI_CLASS] == XM_ELF_CLASS32) {
             if (xm_binutils_elf_get_context_32(istream, base_offset, &ctx)) {
@@ -188,8 +194,6 @@ tb_bool_t xm_binutils_elf_rpath_list(tb_stream_ref_t istream, tb_hize_t base_off
     return ok;
 }
 
-
-
 tb_bool_t xm_binutils_elf_rpath_clean(tb_stream_ref_t istream, tb_hize_t base_offset) {
     tb_assert_and_check_return_val(istream, tb_false);
 
@@ -200,6 +204,7 @@ tb_bool_t xm_binutils_elf_rpath_clean(tb_stream_ref_t istream, tb_hize_t base_of
         if (!tb_stream_seek(istream, base_offset)) break;
         if (!tb_stream_bread(istream, ident, sizeof(ident))) break;
 
+        // build ELF context and cleanup rpath entries
         xm_elf_context_t ctx;
         if (ident[XM_ELF_EI_CLASS] == XM_ELF_CLASS32) {
             if (xm_binutils_elf_get_context_32(istream, base_offset, &ctx)) {