f00aae0f7b
This patch converts the code base to use the new struct event_location
API being introduced. This patch preserves the current functionality and
adds no new features.
The "big picture" API usage introduced by this patch may be illustrated
with a simple exmaple. Where previously developers would write:
void
my_command (char *arg, int from_tty)
{
create_breakpoint (..., arg, ...);
...
}
one now uses:
void
my_command (char *arg, int from_tty)
{
struct event_locaiton *location;
struct cleanup *back_to;
location = string_to_event_locaiton (&arg, ...);
back_to = make_cleanup_delete_event_location (location);
create_breakpoint (..., location, ...);
do_cleanups (back_to);
}
Linespec-decoding functions (now called location-decoding) such as
decode_line_full no longer skip argument pointers over processed input.
That functionality has been moved into string_to_event_location as
demonstrated above.
gdb/ChangeLog
* ax-gdb.c: Include location.h.
(agent_command_1) Use linespec location instead of address
string.
* break-catch-throw.c: Include location.h.
(re_set_exception_catchpoint): Use linespec locations instead
of address strings.
* breakpoint.c: Include location.h.
(create_overlay_event_breakpoint, create_longjmp_master_breakpoint)
(create_std_terminate_master_breakpoint)
(create_exception_master_breakpoint, update_breakpoints_after_exec):
Use linespec location instead of address string.
(print_breakpoint_location): Use locations and
event_location_to_string.
Print extra_string for pending locations for non-MI streams.
(print_one_breakpoint_location): Use locations and
event_location_to_string.
(init_raw_breakpoint_without_location): Initialize b->location.
(create_thread_event_breakpoint): Use linespec location instead of
address string.
(init_breakpoint_sal): Likewise.
Only save extra_string if it is non-NULL and not the empty string.
Use event_location_to_string instead of `addr_string'.
Constify `p' and `endp'.
Use skip_spaces_const/skip_space_const instead of non-const versions.
Copy the location into the breakpoint.
If LOCATION is NULL, save the breakpoint address as a linespec location
instead of an address string.
(create_breakpoint_sal): Change `addr_string' parameter to a struct
event_location. All uses updated.
(create_breakpoints_sal): Likewise for local variable `addr_string'.
(parse_breakpoint_sals): Use locations instead of address strings.
Remove check for empty linespec with conditional.
Refactor.
(decode_static_tracepoint_spec): Make argument const and update
function.
(create_breakpoint): Change `arg' to a struct event_location and
rename.
Remove `copy_arg' and `addr_start'.
If EXTRA_STRING is empty, set it to NULL.
Don't populate `canonical' for pending breakpoints.
Pass `extra_string' to find_condition_and_thread.
Clear `extra_string' if `rest' was NULL.
Do not error with "garbage after location" if setting a dprintf
breakpoint.
Copy the location into the breakpoint instead of an address string.
(break_command_1): Use string_to_event_location and pass this to
create_breakpoint instead of an address string.
Check against `arg_cp' for a probe linespec.
(dprintf_command): Use string_to_event_location and pass this to
create_breakpoint instead of an address string.
Throw an exception if no format string was specified.
(print_recreate_ranged_breakpoint): Use event_location_to_string
instead of address strings.
(break_range_command, until_break_command)
(init_ada_exception_breakpoint): Use locations instead
of address strings.
(say_where): Print out extra_string for pending locations.
(base_breakpoint_dtor): Delete `location' and `location_range_end' of
the breakpoint.
(base_breakpoint_create_sals_from_location): Use struct event_location
instead of address string.
Remove `addr_start' and `copy_arg' parameters.
(base_breakpoint_decode_location): Use struct event_location instead of
address string.
(bkpt_re_set): Use locations instead of address strings.
Use event_location_empty_p to check for unset location.
(bkpt_print_recreate): Use event_location_to_string instead of
an address string.
Print out extra_string for pending locations.
(bkpt_create_sals_from_location, bkpt_decode_location)
(bkpt_probe_create_sals_from_location): Use struct event_location
instead of address string.
(bkpt_probe_decode_location): Use struct event_location instead of
address string.
(tracepoint_print_recreate): Use event_location_to_string to
recreate the tracepoint.
(tracepoint_create_sals_from_location, tracepoint_decode_location)
(tracepoint_probe_create_sals_from_location)
(tracepoint_probe_decode_location): Use struct event_location
instead of address string.
(dprintf_print_recreate): Use event_location_to_string to recreate
the dprintf.
(dprintf_re_set): Remove check for valid/missing format string.
(strace_marker_create_sals_from_location)
(strace_marker_create_breakpoints_sal, strace_marker_decode_location)
(update_static_tracepoint): Use struct event_location instead of
address string.
(location_to_sals): Likewise.
Pass `extra_string' to find_condition_and_thread.
For newly resolved pending breakpoint locations, clear the location's
string representation.
Assert that the breakpoint's condition string is NULL when
condition_not_parsed.
(breakpoint_re_set_default, create_sals_from_location_default)
(decode_location_default, trace_command, ftrace_command)
(strace_command, create_tracepoint_from_upload): Use locations
instead of address strings.
* breakpoint.h (struct breakpoint_ops) <create_sals_from_location>:
Use struct event_location instead of address string.
Update all uses.
<decode_location>: Likewise.
(struct breakpoint) <addr_string>: Change to struct event_location
and rename `location'.
<addr_string_range_end>: Change to struct event_location and rename
`location_range_end'.
(create_breakpoint): Use struct event_location instead of address
string.
* cli/cli-cmds.c: Include location.h.
(edit_command, list_command): Use locations instead of address strings.
* elfread.c: Include location.h.
(elf_gnu_ifunc_resolver_return_stop): Use event_location_to_string.
* guile/scm-breakpoint.c: Include location.h.
(bpscm_print_breakpoint_smob): Use event_location_to_string.
(gdbscm_register_breakpoint): Use locations instead of address
strings.
* linespec.c: Include location.h.
(struct ls_parser) <stream>: Change to const char *.
(PARSER_STREAM): Update.
(lionespec_lexer_lex_keyword): According to find_condition_and_thread,
keywords must be followed by whitespace.
(canonicalize_linespec): Save a linespec location into `canonical'.
Save a canonical linespec into `canonical'.
(parse_linespec): Change `argptr' to const char * and rename `arg'.
All uses updated.
Update function description.
(linespec_parser_new): Initialize `parser'.
Update initialization of parsing stream.
(event_location_to_sals): New function.
(decode_line_full): Change `argptr' to a struct event_location and
rename it `location'.
Use locations instead of address strings.
Call event_location_to_sals instead of parse_linespec.
(decode_line_1): Likewise.
(decode_line_with_current_source, decode_line_with_last_displayed)
Use locations instead of address strings.
(decode_objc): Likewise.
Change `argptr' to const char * and rename `arg'.
(destroy_linespec_result): Delete the linespec result's location
instead of freeing the address string.
* linespec.h (struct linespec_result) <addr_string>: Change to
struct event_location and rename to ...
<location>: ... this.
(decode_line_1, decode_line_full): Change `argptr' to struct
event_location. All callers updated.
* mi/mi-cmd-break.c: Include language.h, location.h, and linespec.h.
(mi_cmd_break_insert_1): Use locations instead of address strings.
Throw an error if there was "garbage" at the end of the specified
linespec.
* probe.c: Include location.h.
(parse_probes): Change `argptr' to struct event_location.
Use event locations instead of address strings.
* probe.h (parse_probes): Change `argptr' to struct event_location.
* python/py-breakpoint.c: Include location.h.
(bppy_get_location): Constify local variable `str'.
Use event_location_to_string.
(bppy_init): Use locations instead of address strings.
* python/py-finishbreakpoint.c: Include location.h.
(bpfinishpy_init): Remove local variable `addr_str'.
Use locations instead of address strings.
* python/python.c: Include location.h.
(gdbpy_decode_line): Use locations instead of address strings.
* remote.c: Include location.h.
(remote_download_tracepoint): Use locations instead of address
strings.
* spu-tdep.c: Include location.h.
(spu_catch_start): Remove local variable `buf'.
Use locations instead of address strings.
* tracepoint.c: Include location.h.
(scope_info): Use locations instead of address strings.
(encode_source_string): Constify parameter `src'.
* tracepoint.h (encode_source_string): Likewise.
gdb/testsuite/ChangeLog
* gdb.base/dprintf-pending.exp: Update dprintf "without format"
test.
Add tests for missing ",FMT" and ",".
|
||
|---|---|---|
| .. | ||
| lib | ||
| guile-internal.h | ||
| guile.c | ||
| guile.h | ||
| README | ||
| scm-arch.c | ||
| scm-auto-load.c | ||
| scm-block.c | ||
| scm-breakpoint.c | ||
| scm-cmd.c | ||
| scm-disasm.c | ||
| scm-exception.c | ||
| scm-frame.c | ||
| scm-gsmob.c | ||
| scm-iterator.c | ||
| scm-lazy-string.c | ||
| scm-math.c | ||
| scm-objfile.c | ||
| scm-param.c | ||
| scm-ports.c | ||
| scm-pretty-print.c | ||
| scm-progspace.c | ||
| scm-safe-call.c | ||
| scm-string.c | ||
| scm-symbol.c | ||
| scm-symtab.c | ||
| scm-type.c | ||
| scm-utils.c | ||
| scm-value.c | ||
README for gdb/guile
====================
This file contains important notes for gdb/guile developers.
["gdb/guile" refers to the directory you found this file in]
Nomenclature:
In the implementation we use "Scheme" or "Guile" depending on context.
And sometimes it doesn't matter.
Guile is Scheme, and for the most part this is what we present to the user
as well. However, to highlight the fact that it is Guile, the GDB commands
that invoke Scheme functions are named "guile" and "guile-repl",
abbreviated "gu" and "gr" respectively.
Co-existence with Python:
Keep the user interfaces reasonably consistent, but don't shy away from
providing a clearer (or more Scheme-friendly/consistent) user interface
where appropriate.
Additions to Python support or Scheme support don't require corresponding
changes in the other scripting language.
Scheme-wrapped breakpoints are created lazily so that if the user
doesn't use Scheme s/he doesn't pay any cost.
Importing the gdb module into Scheme:
To import the gdb module:
(gdb) guile (use-modules (gdb))
If you want to add a prefix to gdb module symbols:
(gdb) guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:)))
This gives every symbol a "gdb:" prefix which is a common convention.
OTOH it's more to type.
Implementation/Hacking notes:
Don't use scm_is_false.
For this C function, () == #f (a la Lisp) and it's not clear how treating
them as equivalent for truth values will affect the GDB interface.
Until the effect is clear avoid them.
Instead use gdbscm_is_false, gdbscm_is_true, gdbscm_is_bool.
There are macros in guile-internal.h to enforce this.
Use gdbscm_foo as the name of functions that implement Scheme procedures
to provide consistent naming in error messages. The user can see "gdbscm"
in the name and immediately know where the function came from.
All smobs contain gdb_smob or chained_gdb_smob as the first member.
This provides a mechanism for extending them in the Scheme side without
tying GDB to the details.
The lifetime of a smob, AIUI, is decided by the containing SCM.
When there is no longer a reference to the containing SCM then the
smob can be GC'd. Objects that have references from outside of Scheme,
e.g., breakpoints, need to be protected from GC.
Don't do something that can cause a Scheme exception inside a TRY_CATCH,
and, in code that can be called from Scheme, don't do something that can
cause a GDB exception outside a TRY_CATCH.
This makes the code a little tricky to write sometimes, but it is a
rule imposed by the programming environment. Bugs often happen because
this rule is broken. Learn it, follow it.
Coding style notes:
- If you find violations to these rules, let's fix the code.
Some attempt has been made to be consistent, but it's early.
Over time we want things to be more consistent, not less.
- None of this really needs to be read. Instead, do not be creative:
Monkey-See-Monkey-Do hacking should generally Just Work.
- Absence of the word "typically" means the rule is reasonably strict.
- The gdbscm_initialize_foo function (e.g., gdbscm_initialize_values)
is the last thing to appear in the file, immediately preceded by any
tables of exported variables and functions.
- In addition to these of course, follow GDB coding conventions.
General naming rules:
- The word "object" absent any modifier (like "GOOPS object") means a
Scheme object (of any type), and is never used otherwise.
If you want to refer to, e.g., a GOOPS object, say "GOOPS object".
- Do not begin any function, global variable, etc. name with scm_.
That's what the Guile implementation uses.
(kinda obvious, just being complete).
- The word "invalid" carries a specific connotation. Try not to use it
in a different way. It means the underlying GDB object has disappeared.
For example, a <gdb:objfile> smob becomes "invalid" when the underlying
objfile is removed from GDB.
- We typically use the word "exception" to mean Scheme exceptions,
and we typically use the word "error" to mean GDB errors.
Comments:
- function comments for functions implementing Scheme procedures begin with
a description of the Scheme usage. Example:
/* (gsmob-aux gsmob) -> object */
- the following comment appears after the copyright header:
/* See README file in this directory for implementation notes, coding
conventions, et.al. */
Smob naming:
- gdb smobs are named, internally, "gdb:foo"
- in Guile they become <gdb:foo>, that is the convention for naming classes
and smobs have rudimentary GOOPS support (they can't be inherited from,
but generics can work with them)
- in comments use the Guile naming for smobs,
i.e., <gdb:foo> instead of gdb:foo.
Note: This only applies to smobs. Exceptions are also named gdb:foo,
but since they are not "classes" they are not wrapped in <>.
- smob names are stored in a global, and for simplicity we pass this
global as the "expected type" parameter to SCM_ASSERT_TYPE, thus in
this instance smob types are printed without the <>.
[Hmmm, this rule seems dated now. Plus I18N rules in GDB are not always
clear, sometimes we pass the smob name through _(), however it's not
clear that's actually a good idea.]
Type naming:
- smob structs are typedefs named foo_smob
Variable naming:
- "scm" by itself is reserved for arbitrary Scheme objects
- variables that are pointers to smob structs are named <char>_smob or
<char><char>_smob, e.g., f_smob for a pointer to a frame smob
- variables that are gdb smob objects are typically named <char>_scm or
<char><char>_scm, e.g., f_scm for a <gdb:frame> object
- the name of the first argument for method-like functions is "self"
Function naming:
General:
- all non-static functions have a prefix,
either gdbscm_ or <char><char>scm_ [or <char><char><char>scm_]
- all functions that implement Scheme procedures have a gdbscm_ prefix,
this is for consistency and readability of Scheme exception text
- static functions typically have a prefix
- the prefix is typically <char><char>scm_ where the first two letters
are unique to the file or class the function works with.
E.g., the scm-arch.c prefix is arscm_.
This follows something used in gdb/python in some places,
we make it formal.
- if the function is of a general nature, or no other prefix works,
use gdbscm_
Conversion functions:
- the from/to in function names follows from libguile's existing style
- conversions from/to Scheme objects are named:
prefix_scm_from_foo: converts from foo to scm
prefix_scm_to_foo: converts from scm to foo
Exception handling:
- functions that may throw a Scheme exception have an _unsafe suffix
- This does not apply to functions that implement Scheme procedures.
- This does not apply to functions whose explicit job is to throw
an exception. Adding _unsafe to gdbscm_throw is kinda superfluous. :-)
- functions that can throw a GDB error aren't adorned with _unsafe
- "_safe" in a function name means it will never throw an exception
- Generally unnecessary, since the convention is to mark the ones that
*can* throw an exception. But sometimes it's useful to highlight the
fact that the function is safe to call without worrying about exception
handling.
- except for functions that implement Scheme procedures, all functions
that can throw exceptions (GDB or Scheme) say so in their function comment
- functions that don't throw an exception, but still need to indicate to
the caller that one happened (i.e., "safe" functions), either return
a <gdb:exception> smob as a result or pass it back via a parameter.
For this reason don't pass back <gdb:exception> smobs for any other
reason. There are functions that explicitly construct <gdb:exception>
smobs. They're obviously the, umm, exception.
Internal functions:
- internal Scheme functions begin with "%" and are intentionally undocumented
in the manual
Standard Guile/Scheme conventions:
- predicates that return Scheme values have the suffix _p and have suffix "?"
in the Scheme procedure's name
- functions that implement Scheme procedures that modify state have the
suffix _x and have suffix "!" in the Scheme procedure's name
- object predicates that return a C truth value are named prefix_is_foo
- functions that set something have "set" at the front (except for a prefix)
write this: gdbscm_set_gsmob_aux_x implements (set-gsmob-aux! ...)
not this: gdbscm_gsmob_set_aux_x implements (gsmob-set-aux! ...)
Doc strings:
- there are lots of existing examples, they should be pretty consistent,
use them as boilerplate/examples
- begin with a one line summary (can be multiple lines if necessary)
- if the arguments need description:
- blank line
- " Arguments: arg1 arg2"
" arg1: blah ..."
" arg2: blah ..."
- if the result requires more description:
- blank line
- " Returns:"
" Blah ..."
- if it's important to list exceptions that can be thrown:
- blank line
- " Throws:"
" exception-name: blah ..."