Reading DWARF not in an object file

If the DWARF you work with is in standard object files (Elf, PE, MacOS) then you can ignore this section entirely. All that this section describes is used, but it's already done for you in functions in the library:

See also: dwarf_init_path dwarf_init_path_dl; dwarf_init_b and; dwarf_finish .

This section describes how to use calls

See also: dwarf_object_init_b; dwarf_object_finish .

These functions are useful if someone is doing just-in-time compilation, and someone working on the code wants to debug this on-the-fly code in a situation where nothing can be written to disc, but DWARF can be constructed in memory.

For a simple example of this with DWARF in local arrays

See also: Demonstrating reading DWARF without a file.

But the libdwarf feature can be useful in a variety of circumstances.

For example, the DWARF data were kept in simple files of bytes on the internet. Or on the local net. Or if files can be written locally each section could be kept in a simple stream of bytes in the local file system.

Another example is a non-standard file system, or file format, with the intent of obfuscating the file or the DWARF.

For this to work the code generator must generate standard DWARF.

Overall the idea is a simple one: You write a small handful of functions and supply function pointers and code implementing the functions. These are part of your application or library, not part of libdwarf. Your code accesses the data in whatever way applies and you write code that provides the interfaces so standard libdwarf can access your DWARF content.

You set up a little bit of data with that code (described below) and then you have essentially written the dwarf_init_path equivalent and you can access compilation units, line tables etc and the standard libdwarf function calls simply work.

Data you need to create involves the following types. What follows describes how to fill them in and how to make them work for you.

typedef struct Dwarf_Obj_Access_Interface_a_s
    Dwarf_Obj_Access_Interface_a;
struct Dwarf_Obj_Access_Interface_a_s {
    void                             *ai_object;
    const Dwarf_Obj_Access_Methods_a *ai_methods;
};
 
typedef struct Dwarf_Obj_Access_Methods_a_s
    Dwarf_Obj_Access_Methods_a
struct Dwarf_Obj_Access_Methods_a_s {
    int    (*om_get_section_info)(void* obj,
        Dwarf_Half                  section_index,
        Dwarf_Obj_Access_Section_a* return_section,
        int                       * error);
    Dwarf_Small      (*om_get_byte_order)(void* obj);
    Dwarf_Small      (*om_get_length_size)(void* obj);
    Dwarf_Small      (*om_get_pointer_size)(void* obj);
    Dwarf_Unsigned   (*om_get_filesize)(void* obj);
    Dwarf_Unsigned   (*om_get_section_count)(void* obj);
    int              (*om_load_section)(void* obj,
        Dwarf_Half    section_index,
        Dwarf_Small** return_data,
        int         * error);
    int              (*om_relocate_a_section)(void* obj,
        Dwarf_Half  section_index,
        Dwarf_Debug dbg,
        int        *error);
};
 
typedef struct Dwarf_Obj_Access_Section_a_s
    Dwarf_Obj_Access_Section_a
struct Dwarf_Obj_Access_Section_a_s {
    const char*    as_name;
    Dwarf_Unsigned as_type;
    Dwarf_Unsigned as_flags;
    Dwarf_Addr     as_addr;
    Dwarf_Unsigned as_offset;
    Dwarf_Unsigned as_size;
    Dwarf_Unsigned as_link;
    Dwarf_Unsigned as_info;
    Dwarf_Unsigned as_addralign;
    Dwarf_Unsigned as_entrysize;
};

Describing the Interface

struct struct Dwarf_Obj_Access_Interface_a_s

Your code must create and fill in this struct's two pointer members. Libdwarf needs these to access your DWARF data. You pass a pointer to this filled-in struct to dwarf_object_init_b. When it is time to conclude all access to the created Dwarf_Debug call dwarf_object_finish . Any allocations you made in setting these things up you must then free after calling dwarf_object_finish .

ai_object

Allocate a local struct (libdwarf will not touch this struct and will not know anything of its contents). You will need one of these for each Dwarf_Debug you open. Put a pointer to this into ai_object. Then fill in all the data you need to access information you will pass back via the ai_methods functions. In the description of the methods functions described later here, this pointer is named obj .

ai_methods

Usually you allocate a static structure and fill it in with function pointers (to functions you write). Then put a pointer to the static structure into this field.

Describing A Section

Dwarf_Obj_Access_Section_a:

The set of fields here is a set that is sufficient to describe a single object section to libdwarf. Your implementation of a om_get_section_info must simply fill in a few fields (leaving most zero) for libdwarf for the section indexed. The fields here are standard Elf, and for most you can just fill in the value zero. For section index zero as_name should be set to an empty string (see below about section index numbers).

as_name: Here you set a section name via the pointer. The section names must be names as defined in the DWARF standard, so if such do not appear in your data you have to create the strings yourself.

as_type: Just fill in zero.

as_flags: Just fill in zero.

as_addr: Fill in the address, in local memory, where the bytes of the section are.

as_offset: Just fill in zero.

as_size: Fill in the size, in bytes, of the section you are telling libdwarf about.

as_link: Just fill in zero.

as_info: Just fill in zero.

as_addralign:Just fill in zero.

as_entrysize: Just fill in one.

Function Pointers

struct Dwarf_Obj_Access_Methods_a_s:

The functions libdwarf needs to access object data are declared here. Usually the struct is statically defined and the function pointers are set at compile time. You must implement these functions based on your knowledge of how the actual data is represented and where to get it.

Each has a first-parameter of obj which is a struct you define to hold data you need to implement this set of functions. You refer to it When libdwarf calls your set of functions (these described now) it passes the ai_object pointer you provided to these functions as obj parameter .

This is the final part of your work for libdwarf. In the source file with your code you will be allocating data, making a provision for an array (real or conceptual) for per-section data, and returning values libdwarf needs. Note that the section array should include an index zero with all zero field values. That means interesting fields start with index one. This special case of index zero Elf is required and matches the standard Elf object format.

Notice that the error argument, where applicable, is an int* . Error codes passed back are DW_DLE codes and dwarf_errmsg_by_number may be used (by your code) to get the standard error string for that error.

om_get_section_info

Get address, size, and name info about a section.
 
Parameters
obj            -  Your data
section_index  - Zero-based index.
return_section - Pointer to a structure in which
    section info will be placed.   Caller must
    provide a valid pointer to a structure area.
    The structure's contents will be overwritten
    by the call to get_section_info.
error          - A pointer to an integer in which an error
    code may be stored.
 
Return
DW_DLV_OK       - Everything ok.
DW_DLV_ERROR    - Error occurred. Use 'error' to determine the
    @e libdwarf defined error.
DW_DLV_NO_ENTRY - No such section.

om_get_byte_order