Next: Adding a New Target, Previous: Adding support for debugging core files, Up: Target Architecture Definition

### 11.10 Defining Other Architecture Features

This section describes other functions and values in `gdbarch`, together with some useful macros, that you can use to define the target architecture.

`CORE_ADDR gdbarch_addr_bits_remove (`gdbarch`,` addr`)`
  If a raw machine instruction address includes any bits that are not really part of the address, then this function is used to zero those bits in addr. This is only used for addresses of instructions, and even then not in all contexts.

  For example, the two low-order bits of the PC on the Hewlett-Packard PA 2.0 architecture contain the privilege level of the corresponding instruction. Since instructions must always be aligned on four-byte boundaries, the processor masks out these bits to generate the actual address of the instruction. `gdbarch_addr_bits_remove` would then for example look like that:

                arch_addr_bits_remove (CORE_ADDR addr)
                {
                  return (addr &= ~0x3);
                }

`int address_class_name_to_type_flags (`gdbarch`,` name`,` type_flags_ptr`)`
  If name is a valid address class qualifier name, set the `int` referenced by type_flags_ptr to the mask representing the qualifier and return 1. If name is not a valid address class qualifier name, return 0.

  The value for type_flags_ptr should be one of `TYPE_FLAG_ADDRESS_CLASS_1`, `TYPE_FLAG_ADDRESS_CLASS_2`, or possibly some combination of these values or'd together. See Address Classes.

`int address_class_name_to_type_flags_p (`gdbarch`)`
  Predicate which indicates whether `address_class_name_to_type_flags` has been defined.
`int gdbarch_address_class_type_flags (`gdbarch`,` byte_size`,` dwarf2_addr_class`)`
  Given a pointers byte size (as described by the debug information) and the possible `DW_AT_address_class` value, return the type flags used by gdb to represent this address class. The value returned should be one of `TYPE_FLAG_ADDRESS_CLASS_1`, `TYPE_FLAG_ADDRESS_CLASS_2`, or possibly some combination of these values or'd together. See Address Classes.
`int gdbarch_address_class_type_flags_p (`gdbarch`)`
  Predicate which indicates whether `gdbarch_address_class_type_flags_p` has been defined.
`const char *gdbarch_address_class_type_flags_to_name (`gdbarch`,` type_flags`)`
  Return the name of the address class qualifier associated with the type flags given by type_flags.
`int gdbarch_address_class_type_flags_to_name_p (`gdbarch`)`
  Predicate which indicates whether `gdbarch_address_class_type_flags_to_name` has been defined. See Address Classes.
`void gdbarch_address_to_pointer (`gdbarch`,` type`,` buf`,` addr`)`
  Store in buf a pointer of type type representing the address addr, in the appropriate format for the current architecture. This function may safely assume that type is either a pointer or a C`++` reference type. See Pointers Are Not Always Addresses.
`int gdbarch_believe_pcc_promotion (`gdbarch`)`
  Used to notify if the compiler promotes a `short` or `char` parameter to an `int`, but still reports the parameter as its original type, rather than the promoted type.
`gdbarch_bits_big_endian (`gdbarch`)`
  This is used if the numbering of bits in the targets does not match the endianism of the target byte order. A value of 1 means that the bits are numbered in a big-endian bit order, 0 means little-endian.
`set_gdbarch_bits_big_endian (`gdbarch`,` bits_big_endian`)`
  Calling set_gdbarch_bits_big_endian with a value of 1 indicates that the bits in the target are numbered in a big-endian bit order, 0 indicates little-endian.
`BREAKPOINT`
  This is the character array initializer for the bit pattern to put into memory where a breakpoint is set. Although it's common to use a trap instruction for a breakpoint, it's not required; for instance, the bit pattern could be an invalid instruction. The breakpoint must be no longer than the shortest instruction of the architecture.

  `BREAKPOINT` has been deprecated in favor of `gdbarch_breakpoint_from_pc`.

`BIG_BREAKPOINT`
`LITTLE_BREAKPOINT`
  Similar to BREAKPOINT, but used for bi-endian targets.

  `BIG_BREAKPOINT` and `LITTLE_BREAKPOINT` have been deprecated in favor of `gdbarch_breakpoint_from_pc`.

`const gdb_byte *gdbarch_breakpoint_from_pc (`gdbarch`,` pcptr`,` lenptr`)`
  Use the program counter to determine the contents and size of a breakpoint instruction. It returns a pointer to a static string of bytes that encode a breakpoint instruction, stores the length of the string to `*`lenptr, and adjusts the program counter (if necessary) to point to the actual memory location where the breakpoint should be inserted. On input, the program counter (`*`pcptr is the encoded inferior's PC register. If software breakpoints are supported, the function sets this argument to the PC's plain address. If software breakpoints are not supported, the function returns NULL instead of the encoded breakpoint instruction.

  Although it is common to use a trap instruction for a breakpoint, it's not required; for instance, the bit pattern could be an invalid instruction. The breakpoint must be no longer than the shortest instruction of the architecture.

  Provided breakpoint bytes can be also used by `bp_loc_is_permanent` to detect permanent breakpoints. `gdbarch_breakpoint_from_pc` should return an unchanged memory copy if it was called for a location with permanent breakpoint as some architectures use breakpoint instructions containing arbitrary parameter value.

  Replaces all the other BREAKPOINT macros.

`int gdbarch_memory_insert_breakpoint (`gdbarch`,` bp_tgt`)`
`gdbarch_memory_remove_breakpoint (`gdbarch`,` bp_tgt`)`
  Insert or remove memory based breakpoints. Reasonable defaults (`default_memory_insert_breakpoint` and `default_memory_remove_breakpoint` respectively) have been provided so that it is not necessary to set these for most architectures. Architectures which may want to set `gdbarch_memory_insert_breakpoint` and `gdbarch_memory_remove_breakpoint` will likely have instructions that are oddly sized or are not stored in a conventional manner.

  It may also be desirable (from an efficiency standpoint) to define custom breakpoint insertion and removal routines if `gdbarch_breakpoint_from_pc` needs to read the target's memory for some reason.

`CORE_ADDR gdbarch_adjust_breakpoint_address (`gdbarch`,` bpaddr`)`
  Given an address at which a breakpoint is desired, return a breakpoint address adjusted to account for architectural constraints on breakpoint placement. This method is not needed by most targets.

  The FR-V target (see `frv-tdep.c`) requires this method. The FR-V is a VLIW architecture in which a number of RISC-like instructions are grouped (packed) together into an aggregate instruction or instruction bundle. When the processor executes one of these bundles, the component instructions are executed in parallel.

  In the course of optimization, the compiler may group instructions from distinct source statements into the same bundle. The line number information associated with one of the latter statements will likely refer to some instruction other than the first one in the bundle. So, if the user attempts to place a breakpoint on one of these latter statements, gdb must be careful to not place the break instruction on any instruction other than the first one in the bundle. (Remember though that the instructions within a bundle execute in parallel, so the first instruction is the instruction at the lowest address and has nothing to do with execution order.)

  The FR-V's `gdbarch_adjust_breakpoint_address` method will adjust a breakpoint's address by scanning backwards for the beginning of the bundle, returning the address of the bundle.

  Since the adjustment of a breakpoint may significantly alter a user's expectation, gdb prints a warning when an adjusted breakpoint is initially set and each time that that breakpoint is hit.

`int gdbarch_call_dummy_location (`gdbarch`)`
  See the file `inferior.h`.

  This method has been replaced by `gdbarch_push_dummy_code` (see gdbarch_push_dummy_code).

`int gdbarch_cannot_fetch_register (`gdbarch`,` regum`)`
  This function should return nonzero if regno cannot be fetched from an inferior process.
`int gdbarch_cannot_store_register (`gdbarch`,` regnum`)`
  This function should return nonzero if regno should not be written to the target. This is often the case for program counters, status words, and other special registers. This function returns 0 as default so that gdb will assume that all registers may be written.
`int gdbarch_convert_register_p (`gdbarch`,` regnum`, struct type *`type`)`
  Return non-zero if register regnum represents data values of type type in a non-standard form. See Using Different Register and Memory Data Representations.
`int gdbarch_fp0_regnum (`gdbarch`)`
  This function returns the number of the first floating point register, if the machine has such registers. Otherwise, it returns -1.
`CORE_ADDR gdbarch_decr_pc_after_break (`gdbarch`)`
  This function shall return the amount by which to decrement the PC after the program encounters a breakpoint. This is often the number of bytes in `BREAKPOINT`, though not always. For most targets this value will be 0.
`DISABLE_UNSETTABLE_BREAK (`addr`)`
  If defined, this should evaluate to 1 if addr is in a shared library in which breakpoints cannot be set and so should be disabled.
`int gdbarch_dwarf2_reg_to_regnum (`gdbarch`,` dwarf2_regnr`)`
  Convert DWARF2 register number dwarf2_regnr into gdb regnum. If not defined, no conversion will be performed.
`int gdbarch_ecoff_reg_to_regnum (`gdbarch`,` ecoff_regnr`)`
  Convert ECOFF register number ecoff_regnr into gdb regnum. If not defined, no conversion will be performed.
`GCC_COMPILED_FLAG_SYMBOL`
`GCC2_COMPILED_FLAG_SYMBOL`
  If defined, these are the names of the symbols that gdb will look for to detect that GCC compiled the file. The default symbols are `gcc_compiled.` and `gcc2_compiled.`, respectively. (Currently only defined for the Delta 68.)
`gdbarch_get_longjmp_target`
  This function determines the target PC address that `longjmp` will jump to, assuming that we have just stopped at a `longjmp` breakpoint. It takes a `CORE_ADDR *` as argument, and stores the target PC value through this pointer. It examines the current state of the machine as needed, typically by using a manually-determined offset into the `jmp_buf`. (While we might like to get the offset from the target's `jmpbuf.h`, that header file cannot be assumed to be available when building a cross-debugger.)
`DEPRECATED_IBM6000_TARGET`
  Shows that we are configured for an IBM RS/6000 system. This conditional should be eliminated (FIXME) and replaced by feature-specific macros. It was introduced in haste and we are repenting at leisure.
`I386_USE_GENERIC_WATCHPOINTS`
  An x86-based target can define this to use the generic x86 watchpoint support; see I386_USE_GENERIC_WATCHPOINTS.
`gdbarch_in_function_epilogue_p (`gdbarch`,` addr`)`
  Returns non-zero if the given addr is in the epilogue of a function. The epilogue of a function is defined as the part of a function where the stack frame of the function already has been destroyed up to the final `return from function call' instruction.
`int gdbarch_in_solib_return_trampoline (`gdbarch`,` pc`,` name`)`
  Define this function to return nonzero if the program is stopped in the trampoline that returns from a shared library.
`target_so_ops.in_dynsym_resolve_code (`pc`)`
  Define this to return nonzero if the program is stopped in the dynamic linker.
`SKIP_SOLIB_RESOLVER (`pc`)`
  Define this to evaluate to the (nonzero) address at which execution should continue to get past the dynamic linker's symbol resolution function. A zero value indicates that it is not important or necessary to set a breakpoint to get through the dynamic linker and that single stepping will suffice.
`CORE_ADDR gdbarch_integer_to_address (`gdbarch`,` type`,` buf`)`
  Define this when the architecture needs to handle non-pointer to address conversions specially. Converts that value to an address according to the current architectures conventions.

  Pragmatics: When the user copies a well defined expression from their source code and passes it, as a parameter, to gdb's `print` command, they should get the same value as would have been computed by the target program. Any deviation from this rule can cause major confusion and annoyance, and needs to be justified carefully. In other words, gdb doesn't really have the freedom to do these conversions in clever and useful ways. It has, however, been pointed out that users aren't complaining about how gdb casts integers to pointers; they are complaining that they can't take an address from a disassembly listing and give it to `x/i`. Adding an architecture method like `gdbarch_integer_to_address` certainly makes it possible for gdb to “get it right” in all circumstances.

  See Pointers Are Not Always Addresses.

`CORE_ADDR gdbarch_pointer_to_address (`gdbarch`,` type`,` buf`)`
  Assume that buf holds a pointer of type type, in the appropriate format for the current architecture. Return the byte address the pointer refers to. See Pointers Are Not Always Addresses.
`void gdbarch_register_to_value(`gdbarch`,` frame`,` regnum`,` type`,` fur`)`
  Convert the raw contents of register regnum into a value of type type. See Using Different Register and Memory Data Representations.
`REGISTER_CONVERT_TO_VIRTUAL(`reg`,` type`,` from`,` to`)`
  Convert the value of register reg from its raw form to its virtual form. See Raw and Virtual Register Representations.
`REGISTER_CONVERT_TO_RAW(`type`,` reg`,` from`,` to`)`
  Convert the value of register reg from its virtual form to its raw form. See Raw and Virtual Register Representations.
`const struct regset *regset_from_core_section (struct gdbarch *` gdbarch`, const char *` sect_name`, size_t` sect_size`)`
  Return the appropriate register set for a core file section with name sect_name and size sect_size.
`SOFTWARE_SINGLE_STEP_P()`
  Define this as 1 if the target does not have a hardware single-step mechanism. The macro `SOFTWARE_SINGLE_STEP` must also be defined.
`SOFTWARE_SINGLE_STEP(`signal`,` insert_breakpoints_p`)`
  A function that inserts or removes (depending on insert_breakpoints_p) breakpoints at each possible destinations of the next instruction. See `sparc-tdep.c` and `rs6000-tdep.c` for examples.
`set_gdbarch_sofun_address_maybe_missing (`gdbarch`,` set`)`
  Somebody clever observed that, the more actual addresses you have in the debug information, the more time the linker has to spend relocating them. So whenever there's some other way the debugger could find the address it needs, you should omit it from the debug info, to make linking faster.

  Calling `set_gdbarch_sofun_address_maybe_missing` with a non-zero argument set indicates that a particular set of hacks of this sort are in use, affecting `N_SO` and `N_FUN` entries in stabs-format debugging information. `N_SO` stabs mark the beginning and ending addresses of compilation units in the text segment. `N_FUN` stabs mark the starts and ends of functions.

  In this case, gdb assumes two things:

  - `N_FUN` stabs have an address of zero. Instead of using those addresses, you should find the address where the function starts by taking the function name from the stab, and then looking that up in the minsyms (the linker/assembler symbol table). In other words, the stab has the name, and the linker/assembler symbol table is the only place that carries the address.
  - `N_SO` stabs have an address of zero, too. You just look at the `N_FUN` stabs that appear before and after the `N_SO` stab, and guess the starting and ending addresses of the compilation unit from them.
`int gdbarch_stabs_argument_has_addr (`gdbarch`,` type`)`
  Define this function to return nonzero if a function argument of type type is passed by reference instead of value.
`CORE_ADDR gdbarch_push_dummy_call (`gdbarch`,` function`,` regcache`,` bp_addr`,` nargs`,` args`,` sp`,` struct_return`,` struct_addr`)`
  Define this to push the dummy frame's call to the inferior function onto the stack. In addition to pushing nargs, the code should push struct_addr (when struct_return is non-zero), and the return address (bp_addr, in inferior's PC register encoding).

  function is a pointer to a `struct value`; on architectures that use function descriptors, this contains the function descriptor value.

  Returns the updated top-of-stack pointer.

`CORE_ADDR gdbarch_push_dummy_code (`gdbarch`,` sp`,` funaddr`,` using_gcc`,` args`,` nargs`,` value_type`,` real_pc`,` bp_addr`,` regcache`)`
  Given a stack based call dummy, push the instruction sequence (including space for a breakpoint) to which the called function should return.

  Set bp_addr to the address at which the breakpoint instruction should be inserted (in inferior's PC register encoding), real_pc to the resume address when starting the call sequence, and return the updated inner-most stack address.

  By default, the stack is grown sufficient to hold a frame-aligned (see frame_align) breakpoint, bp_addr is set to the address reserved for that breakpoint (in inferior's PC register encoding), and real_pc set to funaddr.

  This method replaces `gdbarch_call_dummy_location (`gdbarch`)`.

`int gdbarch_sdb_reg_to_regnum (`gdbarch`,` sdb_regnr`)`
  Use this function to convert sdb register sdb_regnr into gdb regnum. If not defined, no conversion will be done.
`enum return_value_convention gdbarch_return_value (struct gdbarch *`gdbarch`, struct type *`valtype`, struct regcache *`regcache`, void *`readbuf`, const void *`writebuf`)`
  Given a function with a return-value of type rettype, return which return-value convention that function would use.

  gdb currently recognizes two function return-value conventions: `RETURN_VALUE_REGISTER_CONVENTION` where the return value is found in registers; and `RETURN_VALUE_STRUCT_CONVENTION` where the return value is found in memory and the address of that memory location is passed in as the function's first parameter.

  If the register convention is being used, and writebuf is non-`NULL`, also copy the return-value in writebuf into regcache.

  If the register convention is being used, and readbuf is non-`NULL`, also copy the return value from regcache into readbuf (regcache contains a copy of the registers from the just returned function).

  Maintainer note: This method replaces separate predicate, extract, store methods. By having only one method, the logic needed to determine the return-value convention need only be implemented in one place. If gdb were written in an oo language, this method would instead return an object that knew how to perform the register return-value extract and store.

  Maintainer note: This method does not take a gcc_p parameter, and such a parameter should not be added. If an architecture that requires per-compiler or per-function information be identified, then the replacement of rettype with `struct value` function should be pursued.

  Maintainer note: The regcache parameter limits this methods to the inner most frame. While replacing regcache with a `struct frame_info` frame parameter would remove that limitation there has yet to be a demonstrated need for such a change.

`void gdbarch_skip_permanent_breakpoint (`gdbarch`,` regcache`)`
  Advance the inferior's PC past a permanent breakpoint. gdb normally steps over a breakpoint by removing it, stepping one instruction, and re-inserting the breakpoint. However, permanent breakpoints are hardwired into the inferior, and can't be removed, so this strategy doesn't work. Calling `gdbarch_skip_permanent_breakpoint` adjusts the processor's state so that execution will resume just after the breakpoint. This function does the right thing even when the breakpoint is in the delay slot of a branch or jump.
`CORE_ADDR gdbarch_skip_trampoline_code (`gdbarch`,` frame`,` pc`)`
  If the target machine has trampoline code that sits between callers and the functions being called, then define this function to return a new PC that is at the start of the real function.
`int gdbarch_deprecated_fp_regnum (`gdbarch`)`
  If the frame pointer is in a register, use this function to return the number of that register.
`int gdbarch_stab_reg_to_regnum (`gdbarch`,` stab_regnr`)`
  Use this function to convert stab register stab_regnr into gdb regnum. If not defined, no conversion will be done.
`TARGET_CHAR_BIT`
  Number of bits in a char; defaults to 8.
`int gdbarch_char_signed (`gdbarch`)`
  Non-zero if `char` is normally signed on this architecture; zero if it should be unsigned.

  The ISO C standard requires the compiler to treat `char` as equivalent to either `signed char` or `unsigned char`; any character in the standard execution set is supposed to be positive. Most compilers treat `char` as signed, but `char` is unsigned on the IBM S/390, RS6000, and PowerPC targets.

`int gdbarch_double_bit (`gdbarch`)`
  Number of bits in a double float; defaults to `8 * TARGET_CHAR_BIT`.
`int gdbarch_float_bit (`gdbarch`)`
  Number of bits in a float; defaults to `4 * TARGET_CHAR_BIT`.
`int gdbarch_int_bit (`gdbarch`)`
  Number of bits in an integer; defaults to `4 * TARGET_CHAR_BIT`.
`int gdbarch_long_bit (`gdbarch`)`
  Number of bits in a long integer; defaults to `4 * TARGET_CHAR_BIT`.
`int gdbarch_long_double_bit (`gdbarch`)`
  Number of bits in a long double float; defaults to `2 * gdbarch_double_bit (`gdbarch`)`.
`int gdbarch_long_long_bit (`gdbarch`)`
  Number of bits in a long long integer; defaults to `2 * gdbarch_long_bit (`gdbarch`)`.
`int gdbarch_ptr_bit (`gdbarch`)`
  Number of bits in a pointer; defaults to `gdbarch_int_bit (`gdbarch`)`.
`int gdbarch_short_bit (`gdbarch`)`
  Number of bits in a short integer; defaults to `2 * TARGET_CHAR_BIT`.
`void gdbarch_virtual_frame_pointer (`gdbarch`,` pc`,` frame_regnum`,` frame_offset`)`
  Returns a `(`register`,` offset`)` pair representing the virtual frame pointer in use at the code address pc. If virtual frame pointers are not used, a default definition simply returns `gdbarch_deprecated_fp_regnum` (or `gdbarch_sp_regnum`, if no frame pointer is defined), with an offset of zero.
`TARGET_HAS_HARDWARE_WATCHPOINTS`
  If non-zero, the target has support for hardware-assisted watchpoints. See watchpoints, for more details and other related macros.
`int gdbarch_print_insn (`gdbarch`,` vma`,` info`)`
  This is the function used by gdb to print an assembly instruction. It prints the instruction at address vma in debugged memory and returns the length of the instruction, in bytes. This usually points to a function in the `opcodes` library (see Opcodes). info is a structure (of type `disassemble_info`) defined in the header file `include/dis-asm.h`, and used to pass information to the instruction decoding routine.
`frame_id gdbarch_dummy_id (`gdbarch`,` frame`)`
  Given frame return a `struct frame_id` that uniquely identifies an inferior function call's dummy frame. The value returned must match the dummy frame stack value previously saved by `call_function_by_hand`.
`void gdbarch_value_to_register (`gdbarch`,` frame`,` type`,` buf`)`
  Convert a value of type type into the raw contents of a register. See Using Different Register and Memory Data Representations.

Motorola M68K target conditionals.

`BPT_VECTOR`
  Define this to be the 4-bit location of the breakpoint trap vector. If not defined, it will default to `0xf`.
`REMOTE_BPT_VECTOR`
  Defaults to `1`.