Overlay Commands (Debugging with ROCGDB)

Next: Automatic Overlay Debugging, Previous: How Overlays Work, Up: Overlays [Contents][Index]

### 14.2 Overlay Commands

To use ROCGDB’s overlay support, each overlay in your program must correspond to a separate section of the executable file. The section’s virtual memory address and load memory address must be the overlay’s mapped and load addresses. Identifying overlays with sections allows ROCGDB to determine the appropriate address of a function or variable, depending on whether the overlay is mapped or not.

ROCGDB’s overlay commands all start with the word `overlay`; you can abbreviate this as `ov` or `ovly`. The commands are:

`overlay off`

  Disable ROCGDB’s overlay support. When overlay support is disabled, ROCGDB assumes that all functions and variables are always present at their mapped addresses. By default, ROCGDB’s overlay support is disabled.

`overlay manual`

  Enable manual overlay debugging. In this mode, ROCGDB relies on you to tell it which overlays are mapped, and which are not, using the `overlay map-overlay` and `overlay unmap-overlay` commands described below.

`overlay map-overlay overlay`
`overlay map overlay`

  Tell ROCGDB that overlay is now mapped; overlay must be the name of the object file section containing the overlay. When an overlay is mapped, ROCGDB assumes it can find the overlay’s functions and variables at their mapped addresses. ROCGDB assumes that any other overlays whose mapped ranges overlap that of overlay are now unmapped.

`overlay unmap-overlay overlay`
`overlay unmap overlay`

  Tell ROCGDB that overlay is no longer mapped; overlay must be the name of the object file section containing the overlay. When an overlay is unmapped, ROCGDB assumes it can find the overlay’s functions and variables at their load addresses.

`overlay auto`

  Enable automatic overlay debugging. In this mode, ROCGDB consults a data structure the overlay manager maintains in the inferior to see which overlays are mapped. For details, see Automatic Overlay Debugging.

`overlay load-target`
`overlay load`

  Re-read the overlay table from the inferior. Normally, ROCGDB re-reads the table ROCGDB automatically each time the inferior stops, so this command should only be necessary if you have changed the overlay mapping yourself using ROCGDB. This command is only useful when using automatic overlay debugging.

`overlay list-overlays`
`overlay list`

  Display a list of the overlays currently mapped, along with their mapped addresses, load addresses, and sizes.

Normally, when ROCGDB prints a code address, it includes the name of the function the address falls in:

    (gdb) print main
    $3 = {int ()} 0x11a0 <main>

When overlay debugging is enabled, ROCGDB recognizes code in unmapped overlays, and prints the names of unmapped functions with asterisks around them. For example, if `foo` is a function in an unmapped overlay, ROCGDB prints it this way:

    (gdb) overlay list
    No sections are mapped.
    (gdb) print foo
    $5 = {int (int)} 0x100000 <*foo*>

When `foo`’s overlay is mapped, ROCGDB prints the function’s name normally:

    (gdb) overlay list
    Section .ov.foo.text, loaded at 0x100000 - 0x100034,
            mapped at 0x1016 - 0x104a
    (gdb) print foo
    $6 = {int (int)} 0x1016 <foo>

When overlay debugging is enabled, ROCGDB can find the correct address for functions and variables in an overlay, whether or not the overlay is mapped. This allows most ROCGDB commands, like `break` and `disassemble`, to work normally, even on unmapped code. However, ROCGDB’s breakpoint support has some limitations:

- You can set breakpoints in functions in unmapped overlays, as long as ROCGDB can write to the overlay at its load address.
- ROCGDB can not set hardware or simulator-based breakpoints in unmapped overlays. However, if you set a breakpoint at the end of your overlay manager (and tell ROCGDB which overlays are now mapped, if you are using manual overlay management), ROCGDB will re-set its breakpoints properly.

Next: Automatic Overlay Debugging, Previous: How Overlays Work, Up: Overlays [Contents][Index]