[ViewVC] Annotation of: cvs/cvsroot/AnyEvent-GDB/README

NAME
    AnyEvent::GDB - asynchronous GDB machine interface interface

SYNOPSIS
       use AnyEvent::GDB;

DESCRIPTION
    This module is an AnyEvent user, you need to make sure that you use and
    run a supported event loop.

    It implements the GDB MI protocol, which can be used to talk to GDB
    without having to parse the ever changing command syntax aimed at
    humans.

    It properly quotes your commands and parses the data structures returned
    by GDB.

    At the moment, it's in an early stage of development, so expect changes,
    and, over time, further features (such as breakpoint-specific callbacks
    and so on).

EXAMPLE PROGRAM
    To get you started, here is an example program that runs /bin/ls,
    displaying the stopped information when hitting a breakpoint on "_exit":

       use Data::Dump;
       use AnyEvent::GDB;

       our $gdb = new AnyEvent::GDB
          trace => 1,
          on_exec_stopped => sub {
             ddx $_[0];
          },
       ;

       my $done

       ddx $gdb->cmd_sync (file_exec_and_symbols => "/bin/ls");
       ddx $gdb->cmd_sync (break_insert => "_exit");
       ddx $gdb->cmd_sync ("exec_run");

       AE::cv->recv;

  PROTOCOL QUIRKS
   Minus vs. underscores
    The MI protocol uses "-" to separate name components, while in Perl, you
    use "_" for this purpose.

    This module usually accepts either form as input, and always converts
    names with "-" to names with "_", so the "library-loaded" notify might
    become "notify_library_loaded", and the "host-name" result in that event
    is stored in the "host_name" hash element in Perl.

   Output redirection
    Unfortunately, GDB has no (portable) provision to separate GDB
    input/output from program input/output. Obviously, without a distinction
    between program I/O and GDB I/O it becomes impossible to safely control
    GDB.

    There are two ways for you around it: redirect stdin/stdout yourself, or
    set a tty (eg. with the "inferior_set_tty" command).

    Unfortunately, the MI interface does not seem to support any kind of I/O
    redirection, so this module helps you a bit, by setting the
    "exec-wrapper" variable with a console "set" commmand. That is, this
    module does soemthing like this for you, providing proper file
    descriptors fpr your actual stdin and stdout:

       set exec-wrapper <&5 >&6

    The actual I/O redirection operators are also stored in "$gdb->{stdio}",
    so you can even do it yourself, e.gh. when providing your own wrapper:

       $self->cmd_raw ("set exec-wrapper $self->{stdio}", sub { });

    (You need to use a raw command, as the "correct" "gdb_set" MI command
    silently ignores any "exec-wrapper" setting).

  METHODS
    $gdb = new AnyEvent::GDB key => value...
        Create a new GDB object using the given named parameters.

        For initial experiments, it is highly recommended to run with
        tracing or at least "verbose" enabled. And don't forget to provide
        an "on_eof" callback.

           my $gdb = new AnyEvent::GDB
              on_eof => sub {
                 print Qe are done.\n";
              },
              trace => 1; # or verbose => 1, for less output

        exec => $path (default: "gdb")
            The path of the GDB executable.

        args => [$string...] (default: ["-n"])
            An optional array of parameters to pass to GDB. This should not
            be used to load a program executable, use the
            "file_exec_and_symbols", "target_attach" or similar MI commands
            instead.

        trace => $boolean (default: 0)
            If true, then all commands sent to GDB are printed to STDOUT
            prefixed with "> ", and all replies received from GDB are
            printed to STDOUT prefixed with "< ".

        verbose => $boolean (default: true if trace is enabled, false
        otherwise)
            If true, then log output and possibly other information is
            printed to STDOUT.

        on_xxxx => $callback->(...)
            This specifies a callback for a specific event - see the EVENTS
            section later in this document.

    $gdb->cmd_raw ($command, $cb->($class, $results, $console))
        Execute a raw command: $command is sent unchanged to GDB. See "cmd_"
        for a description of the callback arguments.

        Example: execute a CLI command and print its output.

           $gdb->cmd_raw ("info sh", sub {
              print "$_[3]\n";
           });

    $gdb->cmd ($command => [$option...], $parameter..., $cb->($class,
    $results, $console))
        Execute a MI command and invoke the callback with the results.

        $command is a MI command name. The leading minus sign can be
        omitted, and instead of minus signs, you can use underscores, i.e.
        all the following command names are equivalent:

           "-break-insert"   # as documented in the GDB manual
           -break_insert     # using underscores and _ to avoid having to quote
           break_insert      # ditto, when e.g. used to the left of a =>
           "break-insert"    # no leading minus

        The second argument is an optional array reference with options
        (i.e. it can simply be missing). Each $option is either an option
        name (similar rules as with command names, i.e. no initial "--") or
        an array reference with the first element being the option name, and
        the remaining elements being parameters: [$option, $parameter...].

        The remaining arguments, excluding the last one, are simply the
        parameters passed to GDB.

        All options and parameters will be properly quoted.

        When the command is done, the callback $cb will be invoked with
        $class being one of "done", "connected", "error" or "exit" (note:
        not "running"), $results being a has reference with all the
        "variable=value" pairs from the result list.

        $console is an array reference with all the GDB console messages
        written while command executes (for MI commands, this should always
        be "undef" and can be ignored).

        Example: #todo#

    ($results, $console) = $gdb->cmd_sync ($command => [$option...],
    $parameter...]) =item $results = $gdb->cmd_sync ($command =>
    [$option...], $parameter...])
        Like "cmd", but blocks execution until the command has been
        executed, and returns the results if sucessful. Croaks when GDB
        returns with an error.

        This is purely a convenience method for small scripts: since it
        blocks execution using a condvar, it is not suitable to be used
        inside callbacks or modules.

        That is, unless Coro is used - with Coro, you can run multiple
        "cmd_sync" methods concurrently form multiple threads, with no
        issues.

  EVENTS
    AnyEvent::GDB is asynchronous in nature, as the goal of the MI interface
    is to be fully asynchronous. Due to this, a user of this interface must
    be prepared to handle various events.

    When an event is produced, the GDB object will look for the following
    four handlers and, if found, will call each one in order with the GDB
    object and event name (without "on_") as the first two arguments,
    followed by any event-specific arguments:

    on_event method on the GDB object
        Useful when subclassing.

    on_event constructor parameter/object member
        The callback specified as "on_event" parameter to the constructor.

    on_EVENTNAME method on the GDB object
        Again, mainly useful when subclassing.

    on_EVENTNAME constructor parameter/object member
        Any callback specified as "on_EVENTNAME" parameter to the
        constructor.

    You can change callbacks dynamically by simply replacing the
    corresponding "on_XXX" member in the $gdb object:

       $gdb->{on_event} = sub {
          # new event handler
       };

    Here's the list of events with a description of their arguments.

    on_eof => $cb->($gdb, "eof")
        Called whenever GDB closes the connection. After this event, the
        object is partially destroyed and must not be accessed again.

    on_target => $cb->($gdb, "target", $string)
        Output received from the target. Normally, this is sent directly to
        STDOUT by GDB, but remote targets use this hook.

    on_log => $cb->($gdb, "log", $string)
        Log output from GDB. Best printed to STDOUT in interactive sessions.

    on_TYPE => $cb->($gdb, "TYPE", $class, $results)
        Called for GDB "exec", "status" and "notify" event (TYPE is one of
        these three strings). $class is the class of the event, with "-"
        replaced by "_" everywhere.

        For each of these, the GDB object will create *two* events: one for
        TYPE, and one for TYPE_CLASS. Usuaully you should provide the more
        specific event (TYPE_CLASS).

    on_TYPE_CLASS => $cb->($gdb, "TYPE_CLASS", $results)
        Called for GDB "exec", "status" and "notify" event: TYPE is one of
        these three strings, the class of the event (with "-" replaced b
        "_"s) is appended to it to form the TYPE_CLASS (e.g. "exec_stopped"
        or "notify_library_loaded").

  STATUS STORAGE
    The default implementations of the event method store the thread,
    thread_group, recording, library and running status insid ethe $gdb
    object.

    You can access these at any time. Specifically, the following
    information is available:

    "$gdb->{thread_group}{*id*}"
        The "thread_group" member stores a hash for each existing thread
        group. The hash always contains the "id" member, but might also
        contain other members.

    "$gdb->{thread_group}{*id*}{pid}"
        The "pid" member only exists while the thread group is running a
        program, and contaisn the PID of the program.

    "$gdb->{thread_group}{*id*}{exit_code}"
        The "exit_code" member only exists after a program has finished
        executing, and before it is started again, and contains the exit
        code of the program.

    "$gdb->{thread_group}{*id*}{recording}"
        The "recording" member only exists if recording has been previously
        started, and is 1 if recoridng is currently active, and 0 if it has
        been stopped again.

    "$gdb->{thread}{*id*}"
        The "thread" member stores a hash for each existing thread. The hash
        always contains the "id" member with the thread id, and the
        "group_id" member with the corresponding thread group id.

    "$gdb->{thread}{*id*}{running}"
        The "running" member is 1 while the thread is, well, running, and is
        missing otherwise.

    "$gdb->{thread}{*id*}{stopped}"
        The "stopped" member contains the result list from the
        "on_exec_stopped" notification that caused the thread to stop, and
        only exists when the thread is topped.

    "$gdb->{library}{*id*}"
        The "library" member contains all results from the
        "on_library_loaded" event (such as "id", "target_name", "host_name"
        and potentially a "thread_group".

SEE ALSO
    AnyEvent,
    <http://sourceware.org/gdb/current/onlinedocs/gdb/GDB_002fMI.html#GDB_00
    2fMI>.

AUTHOR
       Marc Lehmann <schmorp@schmorp.de>
       http://home.schmorp.de/

Revision:	1.2
Committed:	Mon Dec 31 13:01:22 2012 UTC (11 years, 6 months ago) by root
Branch:	MAIN
CVS Tags:	rel-0_1
Changes since 1.1:	+263 -211 lines
Log Message:	0.1
#	User	Rev	Content
1	root	1.1	NAME
2	root	1.2	AnyEvent::GDB - asynchronous GDB machine interface interface
3	root	1.1
4			SYNOPSIS
5	root	1.2	use AnyEvent::GDB;
6	root	1.1
7	root	1.2	DESCRIPTION
8			This module is an AnyEvent user, you need to make sure that you use and
9			run a supported event loop.
10
11			It implements the GDB MI protocol, which can be used to talk to GDB
12			without having to parse the ever changing command syntax aimed at
13			humans.
14
15			It properly quotes your commands and parses the data structures returned
16			by GDB.
17
18			At the moment, it's in an early stage of development, so expect changes,
19			and, over time, further features (such as breakpoint-specific callbacks
20			and so on).
21
22			EXAMPLE PROGRAM
23			To get you started, here is an example program that runs /bin/ls,
24			displaying the stopped information when hitting a breakpoint on "_exit":
25	root	1.1
26	root	1.2	use Data::Dump;
27			use AnyEvent::GDB;
28	root	1.1
29	root	1.2	our $gdb = new AnyEvent::GDB
30			trace => 1,
31			on_exec_stopped => sub {
32			ddx $_[0];
33			},
34			;
35	root	1.1
36	root	1.2	my $done
37	root	1.1
38	root	1.2	ddx $gdb->cmd_sync (file_exec_and_symbols => "/bin/ls");
39			ddx $gdb->cmd_sync (break_insert => "_exit");
40			ddx $gdb->cmd_sync ("exec_run");
41	root	1.1
42	root	1.2	AE::cv->recv;
43	root	1.1
44	root	1.2	PROTOCOL QUIRKS
45			Minus vs. underscores
46			The MI protocol uses "-" to separate name components, while in Perl, you
47			use "_" for this purpose.
48	root	1.1
49	root	1.2	This module usually accepts either form as input, and always converts
50			names with "-" to names with "_", so the "library-loaded" notify might
51			become "notify_library_loaded", and the "host-name" result in that event
52			is stored in the "host_name" hash element in Perl.
53	root	1.1
54	root	1.2	Output redirection
55			Unfortunately, GDB has no (portable) provision to separate GDB
56			input/output from program input/output. Obviously, without a distinction
57			between program I/O and GDB I/O it becomes impossible to safely control
58			GDB.
59
60			There are two ways for you around it: redirect stdin/stdout yourself, or
61			set a tty (eg. with the "inferior_set_tty" command).
62
63			Unfortunately, the MI interface does not seem to support any kind of I/O
64			redirection, so this module helps you a bit, by setting the
65			"exec-wrapper" variable with a console "set" commmand. That is, this
66			module does soemthing like this for you, providing proper file
67			descriptors fpr your actual stdin and stdout:
68
69			set exec-wrapper <&5 >&6
70	root	1.1
71	root	1.2	The actual I/O redirection operators are also stored in "$gdb->{stdio}",
72			so you can even do it yourself, e.gh. when providing your own wrapper:
73	root	1.1
74	root	1.2	$self->cmd_raw ("set exec-wrapper $self->{stdio}", sub { });
75	root	1.1
76	root	1.2	(You need to use a raw command, as the "correct" "gdb_set" MI command
77			silently ignores any "exec-wrapper" setting).
78	root	1.1
79			METHODS
80	root	1.2	$gdb = new AnyEvent::GDB key => value...
81			Create a new GDB object using the given named parameters.
82	root	1.1
83	root	1.2	For initial experiments, it is highly recommended to run with
84			tracing or at least "verbose" enabled. And don't forget to provide
85			an "on_eof" callback.
86
87			my $gdb = new AnyEvent::GDB
88			on_eof => sub {
89			print Qe are done.\n";
90			},
91			trace => 1; # or verbose => 1, for less output
92
93			exec => $path (default: "gdb")
94			The path of the GDB executable.
95
96			args => [$string...] (default: ["-n"])
97			An optional array of parameters to pass to GDB. This should not
98			be used to load a program executable, use the
99			"file_exec_and_symbols", "target_attach" or similar MI commands
100			instead.
101
102			trace => $boolean (default: 0)
103			If true, then all commands sent to GDB are printed to STDOUT
104			prefixed with "> ", and all replies received from GDB are
105			printed to STDOUT prefixed with "< ".
106
107			verbose => $boolean (default: true if trace is enabled, false
108			otherwise)
109			If true, then log output and possibly other information is
110			printed to STDOUT.
111
112			on_xxxx => $callback->(...)
113			This specifies a callback for a specific event - see the EVENTS
114			section later in this document.
115
116			$gdb->cmd_raw ($command, $cb->($class, $results, $console))
117			Execute a raw command: $command is sent unchanged to GDB. See "cmd_"
118			for a description of the callback arguments.
119
120			Example: execute a CLI command and print its output.
121
122			$gdb->cmd_raw ("info sh", sub {
123			print "$_[3]\n";
124			});
125
126			$gdb->cmd ($command => [$option...], $parameter..., $cb->($class,
127			$results, $console))
128			Execute a MI command and invoke the callback with the results.
129
130			$command is a MI command name. The leading minus sign can be
131			omitted, and instead of minus signs, you can use underscores, i.e.
132			all the following command names are equivalent:
133
134			"-break-insert" # as documented in the GDB manual
135			-break_insert # using underscores and _ to avoid having to quote
136			break_insert # ditto, when e.g. used to the left of a =>
137			"break-insert" # no leading minus
138
139			The second argument is an optional array reference with options
140			(i.e. it can simply be missing). Each $option is either an option
141			name (similar rules as with command names, i.e. no initial "--") or
142			an array reference with the first element being the option name, and
143			the remaining elements being parameters: [$option, $parameter...].
144
145			The remaining arguments, excluding the last one, are simply the
146			parameters passed to GDB.
147
148			All options and parameters will be properly quoted.
149
150			When the command is done, the callback $cb will be invoked with
151			$class being one of "done", "connected", "error" or "exit" (note:
152			not "running"), $results being a has reference with all the
153			"variable=value" pairs from the result list.
154
155			$console is an array reference with all the GDB console messages
156			written while command executes (for MI commands, this should always
157			be "undef" and can be ignored).
158
159			Example: #todo#
160
161			($results, $console) = $gdb->cmd_sync ($command => [$option...],
162			$parameter...]) =item $results = $gdb->cmd_sync ($command =>
163			[$option...], $parameter...])
164			Like "cmd", but blocks execution until the command has been
165			executed, and returns the results if sucessful. Croaks when GDB
166			returns with an error.
167
168			This is purely a convenience method for small scripts: since it
169			blocks execution using a condvar, it is not suitable to be used
170			inside callbacks or modules.
171
172			That is, unless Coro is used - with Coro, you can run multiple
173			"cmd_sync" methods concurrently form multiple threads, with no
174			issues.
175
176			EVENTS
177			AnyEvent::GDB is asynchronous in nature, as the goal of the MI interface
178			is to be fully asynchronous. Due to this, a user of this interface must
179			be prepared to handle various events.
180
181			When an event is produced, the GDB object will look for the following
182			four handlers and, if found, will call each one in order with the GDB
183			object and event name (without "on_") as the first two arguments,
184			followed by any event-specific arguments:
185
186			on_event method on the GDB object
187			Useful when subclassing.
188
189			on_event constructor parameter/object member
190			The callback specified as "on_event" parameter to the constructor.
191
192			on_EVENTNAME method on the GDB object
193			Again, mainly useful when subclassing.
194
195			on_EVENTNAME constructor parameter/object member
196			Any callback specified as "on_EVENTNAME" parameter to the
197			constructor.
198
199			You can change callbacks dynamically by simply replacing the
200			corresponding "on_XXX" member in the $gdb object:
201
202			$gdb->{on_event} = sub {
203			# new event handler
204			};
205
206			Here's the list of events with a description of their arguments.
207
208			on_eof => $cb->($gdb, "eof")
209			Called whenever GDB closes the connection. After this event, the
210			object is partially destroyed and must not be accessed again.
211
212			on_target => $cb->($gdb, "target", $string)
213			Output received from the target. Normally, this is sent directly to
214			STDOUT by GDB, but remote targets use this hook.
215
216			on_log => $cb->($gdb, "log", $string)
217			Log output from GDB. Best printed to STDOUT in interactive sessions.
218
219			on_TYPE => $cb->($gdb, "TYPE", $class, $results)
220			Called for GDB "exec", "status" and "notify" event (TYPE is one of
221			these three strings). $class is the class of the event, with "-"
222			replaced by "_" everywhere.
223
224			For each of these, the GDB object will create two events: one for
225			TYPE, and one for TYPE_CLASS. Usuaully you should provide the more
226			specific event (TYPE_CLASS).
227
228			on_TYPE_CLASS => $cb->($gdb, "TYPE_CLASS", $results)
229			Called for GDB "exec", "status" and "notify" event: TYPE is one of
230			these three strings, the class of the event (with "-" replaced b
231			"_"s) is appended to it to form the TYPE_CLASS (e.g. "exec_stopped"
232			or "notify_library_loaded").
233
234			STATUS STORAGE
235			The default implementations of the event method store the thread,
236			thread_group, recording, library and running status insid ethe $gdb
237			object.
238
239			You can access these at any time. Specifically, the following
240			information is available:
241
242			"$gdb->{thread_group}{id}"
243			The "thread_group" member stores a hash for each existing thread
244			group. The hash always contains the "id" member, but might also
245			contain other members.
246
247			"$gdb->{thread_group}{id}{pid}"
248			The "pid" member only exists while the thread group is running a
249			program, and contaisn the PID of the program.
250
251			"$gdb->{thread_group}{id}{exit_code}"
252			The "exit_code" member only exists after a program has finished
253			executing, and before it is started again, and contains the exit
254			code of the program.
255
256			"$gdb->{thread_group}{id}{recording}"
257			The "recording" member only exists if recording has been previously
258			started, and is 1 if recoridng is currently active, and 0 if it has
259			been stopped again.
260
261			"$gdb->{thread}{id}"
262			The "thread" member stores a hash for each existing thread. The hash
263			always contains the "id" member with the thread id, and the
264			"group_id" member with the corresponding thread group id.
265
266			"$gdb->{thread}{id}{running}"
267			The "running" member is 1 while the thread is, well, running, and is
268			missing otherwise.
269
270			"$gdb->{thread}{id}{stopped}"
271			The "stopped" member contains the result list from the
272			"on_exec_stopped" notification that caused the thread to stop, and
273			only exists when the thread is topped.
274
275			"$gdb->{library}{id}"
276			The "library" member contains all results from the
277			"on_library_loaded" event (such as "id", "target_name", "host_name"
278			and potentially a "thread_group".
279	root	1.1
280			SEE ALSO
281	root	1.2	AnyEvent,
282			<http://sourceware.org/gdb/current/onlinedocs/gdb/GDB_002fMI.html#GDB_00
283			2fMI>.
284	root	1.1
285			AUTHOR
286			Marc Lehmann <schmorp@schmorp.de>
287			http://home.schmorp.de/
288