Add more comments about AIX ABI and AIX system API

Author: Kai Luo

src/symbolize/gimli/libs_aix.rs

@@ -10,6 +10,9 @@ use core::mem;
 
 const EXE_IMAGE_BASE: u64 = 0x100000000;
 
+/// On AIX, we use `loadquery` with `L_GETINFO` flag to query libraries mmapped.
+/// See https://www.ibm.com/docs/en/aix/7.2?topic=l-loadquery-subroutine for
+/// detailed information of `loadquery`.
 pub(super) fn native_libraries() -> Vec<Library> {
     let mut ret = Vec::new();
     unsafe {
@@ -19,7 +22,7 @@ pub(super) fn native_libraries() -> Vec<Library> {
                 libc::L_GETINFO,
                 buffer.as_mut_ptr() as *mut libc::c_char,
                 (mem::size_of::<libc::ld_info>() * buffer.len()) as u32,
-            ) >= 0
+            ) != -1
             {
                 break;
             } else {

src/symbolize/gimli/xcoff.rs

@@ -126,6 +126,10 @@ impl<'a> Object<'a> {
                 let address = sym.address();
                 let size = Self::get_concrete_size(&file, &sym);
                 if name == ".text" || name == ".data" {
+                    // We don't want to include ".text" and ".data" symbols.
+                    // If they are included, since their ranges cover other
+                    // symbols, when searching a symbol for a given address,
+                    // ".text" or ".data" is returned. That's not what we expect.
                     None
                 } else {
                     Some(ParsedSym {
@@ -145,16 +149,19 @@ impl<'a> Object<'a> {
     }
 
     pub fn search_symtab<'b>(&'b self, addr: u64) -> Option<&'b [u8]> {
+        // Symbols, except ".text" and ".data", are sorted and are not overlapped each other,
+        // so we can just perform a binary search here.
         let i = match self.syms.binary_search_by_key(&addr, |sym| sym.address) {
             Ok(i) => i,
             Err(i) => i.checked_sub(1)?,
         };
         let sym = self.syms.get(i)?;
         if (sym.address..sym.address + sym.size).contains(&addr) {
-            // FIXME: Should we trim the leading '.' of
-            // the symbol of a function entry?
-            // If not, the rust mangler might not work properly.
-            // Or we should update rust mangler to trim the leading '.'?
+            // On AIX, for a function call, for example, `foo()`, we have
+            // two symbols `foo` and `.foo`. `foo` references the function
+            // descriptor and `.foo` references the function entry. We trim
+            // the prefix `.` here, so that the rust demangler can work
+            // properly.
             Some(sym.name.trim_start_matches(".").as_bytes())
         } else {
             None

tests/smoke.rs

@@ -9,6 +9,9 @@ fn get_actual_fn_pointer(fp: usize) -> usize {
     // * The environment pointer.
     // Deref `fp` directly so that we can get the address of `fp`'s
     // entry point in text section.
+    //
+    // For TOC, one can find more information in
+    // https://www.ibm.com/docs/en/aix/7.2?topic=program-understanding-programming-toc.
     if cfg!(target_os = "aix") {
         unsafe {
             let actual_fn_entry = *(fp as *const usize);