Overview

A2N maintains a database of modules and symbols and attempts to answer the following questions:

• "What symbol is associated with this address?".
• "What is the code stream associated with this address?".
• "What source file/line number corresponds to this address?".

For the most part all the drudgery of using A2N is hidden by POST. A2N does export an API which allows a user to take advantage of A2N's functionality if they so desire. The API is described in a2n.h and is identical on all supported platforms.

A2N is distributed as liba2n.so on Linux.

Executable formats

  A2N can only recognize and process ELF executables, either 32 or 64-bit.




Debug data formats

  ELF:      ELF symbols exist in the executable image.
            Produces the highest quality symbols.
            * Harvested by A2N:        Yes
            * Line number information: Yes (if available)

  MAP:      Map files are generated by several utilities. They exist only in
            a separate file.  These are some of the utilities that generate
            map files:

            nm -a
                A2N includes a utility named genmap which invokes nm to
                generate a map file.  The kernel map file (System.map) is an example
                of a map generated by nm.
                * Harvested by A2N:        Yes
                * Line number information: No

            objdump -t
                * Harvested by A2N:        No
                * Line number information: No

            readelf -s
                * Harvested by A2N:        No
                * Line number information: No




A2N handles the following types of "symbol" files:

  A2N can only harvest ELF symbols from executables or from MAP files
  generated by nm.




Search path

  The search path is the list of directories where A2N looks for
  symbols.  The default search paths is:

        /symbols:/usr/symbols:~/symbols




A2N symbol harvesting rules


Kernel rules
    
     Information about kernel symbols from /proc/kallsyms is currently appended
     at the end of the trace file. So, if you need only kernel symbols 
     and not the code, you do not need to specify any post option
     for kernel symbols location.

     If user indicates no preference then we choose as follows:
     1) If /proc/kallsyms is readable or kallsyms info appended to swtrace.nrm2,
        try to use that.
        - If it does not contain symbols go to step 2.
        - If it contains symbols harvest them.
        - No validation needed.
        - No code saved.

     2) If /boot/System.map is readable try to use that.
        - If it does not contain symbols go to step 3.
        - If it contains symbols harvest them.
        - Will attempt validation.
        - No code saved.

     3) If /usr/src/linux/vmlinux is readable try to use that.
        - If it does not contain symbols go to step 4.
        - If it contains symbols harvest them.
        - Will attempt validation.
        - If it contains code, and code is requested, harvest it.

     4) Give up.

     If user indicates preference(s) then we try to use that.
     The post option -k kpath specifies the path of the kernel image,
     and -kmap kpath specifies the path of the kernel map.



All other modules/executables

  1) Harvest symbols from on-disk executable if it contains symbols.

  2) Harvest symbols from map file (same name as requested executable
     with ".map" appended to it) if present.

  3) For each directory in the search path (either default or user
     specified) look for a map file and harvest symbols if map file
     present.

  4) Give up.





To obtain the best quality symbols: (1 is highest quality)

  1) Don't strip your executables.

  2) If you do strip them, place the map file in the same directory
     as the executable.




Compiler/Linker flags required:

  None. gcc always generates symbols in the executable. Use the
  -g option to include line number information.




Where do I get symbols from?

  For the kernel you need either:

     a) The non-stripped kernel image file which is usually located in
        /usr/src/linux/vmlinux.
     b) The kernel map file which is usually located in
        /usr/src/linux/System.map.

  For non-operating system applications you either get the symbols from
  the manufacturer or recompile the applications.

  For your own applications you generate the symbols.