Previous: Functions to Access Frame Data, Up: Frame Interpretation

#### 11.7.6 Analyzing Stacks—Frame Sniffers

When a program stops, gdb needs to construct the chain of struct `frame_info` representing the state of the stack using appropriate sniffers.

Each architecture requires appropriate sniffers, but they do not form entries in `struct gdbarch`, since more than one sniffer may be required and a sniffer may be suitable for more than one `struct gdbarch`. Instead sniffers are associated with architectures using the following functions.

- `frame_unwind_append_sniffer` is used to add a new sniffer to analyze THIS frame when given a pointer to the NEXT frame.
- `frame_base_append_sniffer` is used to add a new sniffer which can determine information about the base of a stack frame.
- `frame_base_set_default` is used to specify the default base sniffer.

These functions all take a reference to `struct gdbarch`, so they are associated with a specific architecture. They are usually called in the `gdbarch` initialization function, after the `gdbarch` struct has been set up. Unless a default has been set, the most recently appended sniffer will be tried first.

The main frame unwinding sniffer (as set by `frame_unwind_append_sniffer)` returns a structure specifying a set of sniffing functions:

         struct frame_unwind
         {
            enum frame_type            type;
            frame_this_id_ftype       *this_id;
            frame_prev_register_ftype *prev_register;
            const struct frame_data   *unwind_data;
            frame_sniffer_ftype       *sniffer;
            frame_prev_pc_ftype       *prev_pc;
            frame_dealloc_cache_ftype *dealloc_cache;
         };

The `type` field indicates the type of frame this sniffer can handle: normal, dummy (see Functions Creating Dummy Frames), signal handler or sentinel. Signal handlers sometimes have their own simplified stack structure for efficiency, so may need their own handlers.

The `unwind_data` field holds additional information which may be relevant to particular types of frame. For example it may hold additional information for signal handler frames.

The remaining fields define functions that yield different types of information when given a pointer to the NEXT stack frame. Not all functions need be provided. If an entry is `NULL`, the next sniffer will be tried instead.

- `this_id` determines the stack pointer and function (code entry point) for THIS stack frame.
- `prev_register` determines where the values of registers for the PREVIOUS stack frame are stored in THIS stack frame.
- `sniffer` takes a look at THIS frame's registers to determine if this is the appropriate unwinder.
- `prev_pc` determines the program counter for THIS frame. Only needed if the program counter is not an ordinary register (see Functions and Variables Specifying the Register Architecture).
- `dealloc_cache` frees any additional memory associated with the prologue cache for this frame (see Prologue Caches).

In general it is only the `this_id` and `prev_register` fields that need be defined for custom sniffers.

The frame base sniffer is much simpler. It is a `struct frame_base`, which refers to the corresponding `frame_unwind` struct and whose fields refer to functions yielding various addresses within the frame.

         struct frame_base
         {
            const struct frame_unwind *unwind;
            frame_this_base_ftype     *this_base;
            frame_this_locals_ftype   *this_locals;
            frame_this_args_ftype     *this_args;
         };

All the functions referred to take a pointer to the NEXT frame as argument. The function referred to by `this_base` returns the base address of THIS frame, the function referred to by `this_locals` returns the base address of local variables in THIS frame and the function referred to by `this_args` returns the base address of the function arguments in this frame.

As described above, the base address of a frame is the address immediately before the start of the NEXT frame. For a falling stack, this is the lowest address in the frame and for a rising stack it is the highest address in the frame. For most architectures the same address is also the base address for local variables and arguments, in which case the same function can be used for all three entries1.

#### Footnotes

[1] It is worth noting that if it cannot be determined in any other way (for example by there being a register with the name `"fp"`), then the result of the `this_base` function will be used as the value of the frame pointer variable `$fp` in gdb. This is very often not correct (for example with the OpenRISC 1000, this value is the stack pointer, `$sp`). In this case a register (raw or pseudo) with the name `"fp"` should be defined. It will be used in preference as the value of `$fp`.