From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 6394 invoked by alias); 13 May 2009 10:36:22 -0000 Received: (qmail 6384 invoked by uid 22791); 13 May 2009 10:36:21 -0000 X-SWARE-Spam-Status: No, hits=-2.2 required=5.0 tests=AWL,BAYES_00,J_CHICKENPOX_37,SPF_PASS X-Spam-Check-By: sourceware.org Received: from mx.southnet.co.nz (HELO viper.snap.net.nz) (202.37.101.20) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Wed, 13 May 2009 10:36:15 +0000 Received: from totara (3.62.255.123.dynamic.snap.net.nz [123.255.62.3]) by viper.snap.net.nz (Postfix) with ESMTP id 216B83DA29D for ; Wed, 13 May 2009 22:36:12 +1200 (NZST) Received: by totara (Postfix, from userid 1000) id 2B68CC13E; Wed, 13 May 2009 22:36:11 +1200 (NZST) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <18954.41627.111280.24736@totara.tehura.co.nz> Date: Wed, 13 May 2009 10:36:00 -0000 To: gdb-patches@sourceware.org Subject: [PATCH] GDB/MI documentation From: nickrob@snap.net.nz (Nick Roberts) X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2009-05/txt/msg00269.txt.bz2 I think it would be quite easy to read GDB/MI General Design and still not understand the overall purpose of GDB/MI. It dives straight into detail about notifications which appear to be buried much later in the node called GDB/MI Async Records. Perhaps there could be some background mentioning annotations as a predecessor and saying `something like': The problem with annotations is that it marks up output intended for a human to read. That means that the syntax might change at any time. In contrast, MI is more formal output intended for parsing by computers, that should provide a more robust interface. Here are just a few basic changes that preserve the content. -- Nick http://www.inet.net.nz/~nickrob 2009-05-13 Nick Roberts * gdb.texinfo (GDB/MI General Design): Break up into four nodes. Simplify English. *** gdb.texinfo 13 May 2009 17:43:30 +1200 1.591 --- gdb.texinfo 13 May 2009 21:54:04 +1200 *************** may repeat one or more times. *** 19788,19804 **** @cindex GDB/MI General Design Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three ! parts---commands sent to @value{GDBN}, responses to those commands and notifications. Each command results in exactly one response, indicating either successful completion of the command, or an error. ! For the commands that do not resume the target, the response contains the ! requested information. For the commands that resume the target, the response only indicates whether the target was successfully resumed. ! Notifications is the mechanism for reporting changes in the state of the target, or in @value{GDBN} state, that cannot conveniently be associated with a command and reported as part of that command response. ! The important examples of notifications are: @itemize @bullet @item --- 19788,19805 ---- @cindex GDB/MI General Design Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three ! parts: commands sent to @value{GDBN}; responses to those commands; and notifications. Each command results in exactly one response, indicating either successful completion of the command, or an error. ! For commands that do not resume the target, the response contains the ! requested information, while for those that do resume the target, the response only indicates whether the target was successfully resumed. ! Notifications are used for reporting changes in the state of the target, or in @value{GDBN} state, that cannot conveniently be associated with a command and reported as part of that command response. ! Important types of notifications are: ! @itemize @bullet @item *************** processed. Therefore, whenever an MI co *** 19834,19839 **** --- 19835,19848 ---- we recommend that the frontend refreshes all the information shown in the user interface. + + @menu + * Context management:: + * Asynchronous command execution and non-stop mode:: + * Thread groups:: + @end menu + + @node Context management @subsection Context management In most cases when @value{GDBN} accesses the target, this access is *************** all subsequent commands. No frontend is *** 19886,19891 **** --- 19895,19901 ---- right, so it is suggested to just always pass the @samp{--thread} and @samp{--frame} options. + @node Asynchronous command execution and non-stop mode @subsection Asynchronous command execution and non-stop mode On some targets, @value{GDBN} is capable of processing MI commands *************** highly target dependent. However, the t *** 19921,19926 **** --- 19931,19937 ---- @code{-exec-interrupt}, to stop a thread, and @code{-thread-info}, to find the state of a thread, will always work. + @node Thread groups @subsection Thread groups @value{GDBN} may be used to debug several processes at the same time. On some platfroms, @value{GDBN} may support debugging of several