MI handshaking

MI handshaking

[Bob Rossi]

Hi,

Here is a simple patch that I think will make everyone happy. It allows
the MI to handshake with the front end.

   * It prints all the stable MI versions ( currently only 1 )
   * If there is more than one stable version ( which there isn't ) it 
     let's the front end select the protocol to use.

This happens only when the front end selects -i=mi, anything like -i=mi2
will go directly to mi2 without the output.

The one question I have is, should the documentation for this be in the
MI output syntax? or should there me a new field called 
MI handshaking syntax?

Thanks,
Bob Rossi

     * interps.c (struct interp): add field, handshake
     (interp_new): Add parameter, handshake
     (interp_can_handshake,interp_handshake): add function definitions
     * interps.h (interp_handshake_ftype): add typedef
     (interp_new): Add parameter, handshake
     (interp_can_handshake,interp_handshake): add function prototype
     * main.c (captured_main): Add the handshaking code
     * cli/cli-interp.c (_initialize_cli_interp): changed interface to
     interp_new
     * mi/mi-interp.c (stable_mi_versions): add table of stable MI versions
     (mi_handshake): Add function to do handshaking
     (_initialize_mi_interp): changed interface to interp_new
     * tui/tui-interp.c (_initialize_tui_interp): changed interface to
     interp_new

Index: interps.c
===================================================================
RCS file: /cvs/src/src/gdb/interps.c,v
retrieving revision 1.8
diff -w -u -r1.8 interps.c
--- interps.c	13 Sep 2004 18:26:30 -0000	1.8
+++ interps.c	4 Nov 2004 19:05:33 -0000
@@ -68,6 +68,8 @@
 
   const struct interp_procs *procs;
   int quiet_p;
+
+  interp_handshake_ftype *handshake;
 };
 
 /* Functions local to this file. */
@@ -90,7 +92,7 @@
    interpreter. */
 struct interp *
 interp_new (const char *name, void *data, struct ui_out *uiout,
-	    const struct interp_procs *procs)
+	    const struct interp_procs *procs, interp_handshake_ftype *handshake)
 {
   struct interp *new_interp;
 
@@ -102,6 +104,7 @@
   new_interp->quiet_p = 0;
   new_interp->procs = procs;
   new_interp->inited = 0;
+  new_interp->handshake = handshake;
 
   return new_interp;
 }
@@ -239,6 +242,22 @@
   return current_interpreter->interpreter_out;
 }
 
+int
+interp_can_handshake (struct interp *interp)
+{
+  if (interp != NULL)
+    if (interp->handshake)
+      return 1;
+
+  return 0;
+}
+
+struct interp *
+interp_handshake (struct interp *interp) 
+{
+    return interp_lookup (interp->handshake (gdb_stdout, gdb_stdin));
+}
+
 /* Returns true if the current interp is the passed in name. */
 int
 current_interp_named_p (const char *interp_name)
Index: interps.h
===================================================================
RCS file: /cvs/src/src/gdb/interps.h,v
retrieving revision 1.6
diff -w -u -r1.6 interps.h
--- interps.h	18 Feb 2004 19:01:36 -0000	1.6
+++ interps.h	4 Nov 2004 19:05:33 -0000
@@ -40,6 +40,7 @@
 typedef int (interp_prompt_p_ftype) (void *data);
 typedef int (interp_exec_ftype) (void *data, const char *command);
 typedef void (interp_command_loop_ftype) (void *data);
+typedef const char *(interp_handshake_ftype) (struct ui_file *gdb_stdout, struct ui_file *gdb_stdin);
 
 struct interp_procs
 {
@@ -53,11 +54,14 @@
 
 extern struct interp *interp_new (const char *name, void *data,
 				  struct ui_out *uiout,
-				  const struct interp_procs *procs);
+		const struct interp_procs *procs,
+		interp_handshake_ftype *handshake);
 extern void interp_add (struct interp *interp);
 extern int interp_set (struct interp *interp);
 extern struct interp *interp_lookup (const char *name);
 extern struct ui_out *interp_ui_out (struct interp *interp);
+extern int interp_can_handshake (struct interp *interp);
+extern struct interp *interp_handshake (struct interp *interp);
 
 extern int current_interp_named_p (const char *name);
 extern int current_interp_display_prompt_p (void);
Index: main.c
===================================================================
RCS file: /cvs/src/src/gdb/main.c,v
retrieving revision 1.44
diff -w -u -r1.44 main.c
--- main.c	10 Aug 2004 22:36:39 -0000	1.44
+++ main.c	4 Nov 2004 19:05:34 -0000
@@ -561,8 +561,13 @@
   {
     /* Find it.  */
     struct interp *interp = interp_lookup (interpreter_p);
+
+    if (interp && interp_can_handshake (interp))
+		interp = interp_handshake (interp);
+
     if (interp == NULL)
       error ("Interpreter `%s' unrecognized", interpreter_p);
+
     /* Install it.  */
     if (!interp_set (interp))
       {
Index: cli/cli-interp.c
===================================================================
RCS file: /cvs/src/src/gdb/cli/cli-interp.c,v
retrieving revision 1.4
diff -w -u -r1.4 cli-interp.c
--- cli/cli-interp.c	3 Jul 2003 14:49:26 -0000	1.4
+++ cli/cli-interp.c	4 Nov 2004 19:05:34 -0000
@@ -151,7 +151,7 @@
 
   /* Create a default uiout builder for the CLI. */
   cli_uiout = cli_out_new (gdb_stdout);
-  cli_interp = interp_new (INTERP_CONSOLE, NULL, cli_uiout, &procs);
+  cli_interp = interp_new (INTERP_CONSOLE, NULL, cli_uiout, &procs, NULL);
 
   interp_add (cli_interp);
 }
Index: mi/mi-interp.c
===================================================================
RCS file: /cvs/src/src/gdb/mi/mi-interp.c,v
retrieving revision 1.11
diff -w -u -r1.11 mi-interp.c
--- mi/mi-interp.c	13 Sep 2004 18:26:31 -0000	1.11
+++ mi/mi-interp.c	4 Nov 2004 19:05:34 -0000
@@ -364,6 +364,66 @@
   start_event_loop ();
 }
 
+/* The latest stable mi version that is being tested.
+   There could potentially be several versions of MI that are stable
+   at a time. */
+static const int stable_mi_versions[] = 
+{
+  2,
+  0
+};
+
+/* Allows MI and the front end to agree on an MI protocol.
+   
+   All of the stable MI versions are currently printed. If there is more
+   than one stable MI version, than it is expected the user will write
+   back the version they want to communicate with. 
+   
+   Returns the MI version string the user requested, or if there is only
+   one version, that string is returned. */
+static const char *mi_handshake (struct ui_file *gdb_stdout,
+	struct ui_file *gdb_stdin)
+{
+  static char mi_buf[32]; 
+  int i;
+
+  if (!gdb_stdout || !gdb_stdin)
+	  return NULL;
+
+  /* Output the header, can't use mi_out stuff because no mi has
+	 been chosen and initialized yet. */
+  fprintf_unfiltered ( gdb_stdout, "mi_handshake={" );
+
+  /* Output all the stable versions */
+  for (i = 0; stable_mi_versions[i] != 0; ++i ) 
+    {
+      if (i > 0)
+        fprintf_unfiltered (gdb_stdout, ",");
+
+        fprintf_unfiltered (gdb_stdout, "stable=mi%d", stable_mi_versions[i] );
+    }
+
+  fprintf_unfiltered ( gdb_stdout, "}\n" );
+	
+  /* If there was more than one stable version outputted, ask the front
+	 end which one it should use */
+  if ( i > 1 ) 
+  {
+    int size;
+	size = ui_file_read ( gdb_stdin, mi_buf, 31 );
+	mi_buf[size--] = 0; /* null terminate, and remove new line */
+	while ( size >= 0 && (mi_buf[size] == '\n' || mi_buf[size] == '\r') )
+      mi_buf[size--] = 0;
+
+	/* The mi option is not valid in this mode. */
+	if ( strcmp ( mi_buf, "mi" ) == 0 )
+      return NULL;
+  } else
+    sprintf ( mi_buf, "mi%d", stable_mi_versions[0] );
+
+  return mi_buf;
+}
+
 extern initialize_file_ftype _initialize_mi_interp; /* -Wmissing-prototypes */
 
 void
@@ -379,11 +439,11 @@
   };
 
   /* The various interpreter levels.  */
-  interp_add (interp_new (INTERP_MI1, NULL, mi_out_new (1), &procs));
-  interp_add (interp_new (INTERP_MI2, NULL, mi_out_new (2), &procs));
-  interp_add (interp_new (INTERP_MI3, NULL, mi_out_new (3), &procs));
+  interp_add (interp_new (INTERP_MI1, NULL, mi_out_new (1), &procs, NULL));
+  interp_add (interp_new (INTERP_MI2, NULL, mi_out_new (2), &procs, NULL));
+  interp_add (interp_new (INTERP_MI3, NULL, mi_out_new (3), &procs, NULL));
 
   /* "mi" selects the most recent released version.  "mi2" was
      released as part of GDB 6.0.  */
-  interp_add (interp_new (INTERP_MI, NULL, mi_out_new (2), &procs));
+  interp_add (interp_new (INTERP_MI, NULL, mi_out_new (stable_mi_versions[0]), &procs, mi_handshake));
 }
Index: tui/tui-interp.c
===================================================================
RCS file: /cvs/src/src/gdb/tui/tui-interp.c,v
retrieving revision 1.5
diff -w -u -r1.5 tui-interp.c
--- tui/tui-interp.c	7 Feb 2004 04:40:36 -0000	1.5
+++ tui/tui-interp.c	4 Nov 2004 19:05:35 -0000
@@ -198,7 +198,7 @@
 
   /* Create a default uiout builder for the TUI. */
   tui_out = tui_out_new (gdb_stdout);
-  interp_add (interp_new ("tui", NULL, tui_out, &procs));
+  interp_add (interp_new ("tui", NULL, tui_out, &procs, NULL));
   if (interpreter_p && strcmp (interpreter_p, "tui") == 0)
     tui_start_enabled = 1;
 

Re: MI handshaking

[Bob Rossi]

BTW, here is an example of how it looks,

$ ../../objdir3/gdb/gdb -i=mi
mi_handshake={stable=mi2}
~"GNU gdb 6.3.50_2004-11-04-cvs\n"
~"Copyright 2004 Free Software Foundation, Inc.\n"
~"GDB is free software, covered by the GNU General Public License, and you are\n"
~"welcome to change it and/or distribute copies of it under certain conditions.\n"
~"Type \"show copying\" to see the conditions.\n"
~"There is absolutely no warranty for GDB.  Type \"show warranty\" for details.\n"
~"This GDB was configured as \"i686-pc-linux-gnu\"."
~"\n"
(gdb)

I can obviously change the syntax of the output if it is desired.
There should probably be a '~' or something like that, any suggestions?

Bob Rossi



On Thu, Nov 04, 2004 at 02:57:01PM -0500, Bob Rossi wrote:
> Hi,
> 
> Here is a simple patch that I think will make everyone happy. It allows
> the MI to handshake with the front end.
> 
>    * It prints all the stable MI versions ( currently only 1 )
>    * If there is more than one stable version ( which there isn't ) it 
>      let's the front end select the protocol to use.
> 
> This happens only when the front end selects -i=mi, anything like -i=mi2
> will go directly to mi2 without the output.
> 
> The one question I have is, should the documentation for this be in the
> MI output syntax? or should there me a new field called 
> MI handshaking syntax?
> 
> Thanks,
> Bob Rossi
> 
>      * interps.c (struct interp): add field, handshake
>      (interp_new): Add parameter, handshake
>      (interp_can_handshake,interp_handshake): add function definitions
>      * interps.h (interp_handshake_ftype): add typedef
>      (interp_new): Add parameter, handshake
>      (interp_can_handshake,interp_handshake): add function prototype
>      * main.c (captured_main): Add the handshaking code
>      * cli/cli-interp.c (_initialize_cli_interp): changed interface to
>      interp_new
>      * mi/mi-interp.c (stable_mi_versions): add table of stable MI versions
>      (mi_handshake): Add function to do handshaking
>      (_initialize_mi_interp): changed interface to interp_new
>      * tui/tui-interp.c (_initialize_tui_interp): changed interface to
>      interp_new
> 
> Index: interps.c
> ===================================================================
> RCS file: /cvs/src/src/gdb/interps.c,v
> retrieving revision 1.8
> diff -w -u -r1.8 interps.c
> --- interps.c	13 Sep 2004 18:26:30 -0000	1.8
> +++ interps.c	4 Nov 2004 19:05:33 -0000
> @@ -68,6 +68,8 @@
>  
>    const struct interp_procs *procs;
>    int quiet_p;
> +
> +  interp_handshake_ftype *handshake;
>  };
>  
>  /* Functions local to this file. */
> @@ -90,7 +92,7 @@
>     interpreter. */
>  struct interp *
>  interp_new (const char *name, void *data, struct ui_out *uiout,
> -	    const struct interp_procs *procs)
> +	    const struct interp_procs *procs, interp_handshake_ftype *handshake)
>  {
>    struct interp *new_interp;
>  
> @@ -102,6 +104,7 @@
>    new_interp->quiet_p = 0;
>    new_interp->procs = procs;
>    new_interp->inited = 0;
> +  new_interp->handshake = handshake;
>  
>    return new_interp;
>  }
> @@ -239,6 +242,22 @@
>    return current_interpreter->interpreter_out;
>  }
>  
> +int
> +interp_can_handshake (struct interp *interp)
> +{
> +  if (interp != NULL)
> +    if (interp->handshake)
> +      return 1;
> +
> +  return 0;
> +}
> +
> +struct interp *
> +interp_handshake (struct interp *interp) 
> +{
> +    return interp_lookup (interp->handshake (gdb_stdout, gdb_stdin));
> +}
> +
>  /* Returns true if the current interp is the passed in name. */
>  int
>  current_interp_named_p (const char *interp_name)
> Index: interps.h
> ===================================================================
> RCS file: /cvs/src/src/gdb/interps.h,v
> retrieving revision 1.6
> diff -w -u -r1.6 interps.h
> --- interps.h	18 Feb 2004 19:01:36 -0000	1.6
> +++ interps.h	4 Nov 2004 19:05:33 -0000
> @@ -40,6 +40,7 @@
>  typedef int (interp_prompt_p_ftype) (void *data);
>  typedef int (interp_exec_ftype) (void *data, const char *command);
>  typedef void (interp_command_loop_ftype) (void *data);
> +typedef const char *(interp_handshake_ftype) (struct ui_file *gdb_stdout, struct ui_file *gdb_stdin);
>  
>  struct interp_procs
>  {
> @@ -53,11 +54,14 @@
>  
>  extern struct interp *interp_new (const char *name, void *data,
>  				  struct ui_out *uiout,
> -				  const struct interp_procs *procs);
> +		const struct interp_procs *procs,
> +		interp_handshake_ftype *handshake);
>  extern void interp_add (struct interp *interp);
>  extern int interp_set (struct interp *interp);
>  extern struct interp *interp_lookup (const char *name);
>  extern struct ui_out *interp_ui_out (struct interp *interp);
> +extern int interp_can_handshake (struct interp *interp);
> +extern struct interp *interp_handshake (struct interp *interp);
>  
>  extern int current_interp_named_p (const char *name);
>  extern int current_interp_display_prompt_p (void);
> Index: main.c
> ===================================================================
> RCS file: /cvs/src/src/gdb/main.c,v
> retrieving revision 1.44
> diff -w -u -r1.44 main.c
> --- main.c	10 Aug 2004 22:36:39 -0000	1.44
> +++ main.c	4 Nov 2004 19:05:34 -0000
> @@ -561,8 +561,13 @@
>    {
>      /* Find it.  */
>      struct interp *interp = interp_lookup (interpreter_p);
> +
> +    if (interp && interp_can_handshake (interp))
> +		interp = interp_handshake (interp);
> +
>      if (interp == NULL)
>        error ("Interpreter `%s' unrecognized", interpreter_p);
> +
>      /* Install it.  */
>      if (!interp_set (interp))
>        {
> Index: cli/cli-interp.c
> ===================================================================
> RCS file: /cvs/src/src/gdb/cli/cli-interp.c,v
> retrieving revision 1.4
> diff -w -u -r1.4 cli-interp.c
> --- cli/cli-interp.c	3 Jul 2003 14:49:26 -0000	1.4
> +++ cli/cli-interp.c	4 Nov 2004 19:05:34 -0000
> @@ -151,7 +151,7 @@
>  
>    /* Create a default uiout builder for the CLI. */
>    cli_uiout = cli_out_new (gdb_stdout);
> -  cli_interp = interp_new (INTERP_CONSOLE, NULL, cli_uiout, &procs);
> +  cli_interp = interp_new (INTERP_CONSOLE, NULL, cli_uiout, &procs, NULL);
>  
>    interp_add (cli_interp);
>  }
> Index: mi/mi-interp.c
> ===================================================================
> RCS file: /cvs/src/src/gdb/mi/mi-interp.c,v
> retrieving revision 1.11
> diff -w -u -r1.11 mi-interp.c
> --- mi/mi-interp.c	13 Sep 2004 18:26:31 -0000	1.11
> +++ mi/mi-interp.c	4 Nov 2004 19:05:34 -0000
> @@ -364,6 +364,66 @@
>    start_event_loop ();
>  }
>  
> +/* The latest stable mi version that is being tested.
> +   There could potentially be several versions of MI that are stable
> +   at a time. */
> +static const int stable_mi_versions[] = 
> +{
> +  2,
> +  0
> +};
> +
> +/* Allows MI and the front end to agree on an MI protocol.
> +   
> +   All of the stable MI versions are currently printed. If there is more
> +   than one stable MI version, than it is expected the user will write
> +   back the version they want to communicate with. 
> +   
> +   Returns the MI version string the user requested, or if there is only
> +   one version, that string is returned. */
> +static const char *mi_handshake (struct ui_file *gdb_stdout,
> +	struct ui_file *gdb_stdin)
> +{
> +  static char mi_buf[32]; 
> +  int i;
> +
> +  if (!gdb_stdout || !gdb_stdin)
> +	  return NULL;
> +
> +  /* Output the header, can't use mi_out stuff because no mi has
> +	 been chosen and initialized yet. */
> +  fprintf_unfiltered ( gdb_stdout, "mi_handshake={" );
> +
> +  /* Output all the stable versions */
> +  for (i = 0; stable_mi_versions[i] != 0; ++i ) 
> +    {
> +      if (i > 0)
> +        fprintf_unfiltered (gdb_stdout, ",");
> +
> +        fprintf_unfiltered (gdb_stdout, "stable=mi%d", stable_mi_versions[i] );
> +    }
> +
> +  fprintf_unfiltered ( gdb_stdout, "}\n" );
> +	
> +  /* If there was more than one stable version outputted, ask the front
> +	 end which one it should use */
> +  if ( i > 1 ) 
> +  {
> +    int size;
> +	size = ui_file_read ( gdb_stdin, mi_buf, 31 );
> +	mi_buf[size--] = 0; /* null terminate, and remove new line */
> +	while ( size >= 0 && (mi_buf[size] == '\n' || mi_buf[size] == '\r') )
> +      mi_buf[size--] = 0;
> +
> +	/* The mi option is not valid in this mode. */
> +	if ( strcmp ( mi_buf, "mi" ) == 0 )
> +      return NULL;
> +  } else
> +    sprintf ( mi_buf, "mi%d", stable_mi_versions[0] );
> +
> +  return mi_buf;
> +}
> +
>  extern initialize_file_ftype _initialize_mi_interp; /* -Wmissing-prototypes */
>  
>  void
> @@ -379,11 +439,11 @@
>    };
>  
>    /* The various interpreter levels.  */
> -  interp_add (interp_new (INTERP_MI1, NULL, mi_out_new (1), &procs));
> -  interp_add (interp_new (INTERP_MI2, NULL, mi_out_new (2), &procs));
> -  interp_add (interp_new (INTERP_MI3, NULL, mi_out_new (3), &procs));
> +  interp_add (interp_new (INTERP_MI1, NULL, mi_out_new (1), &procs, NULL));
> +  interp_add (interp_new (INTERP_MI2, NULL, mi_out_new (2), &procs, NULL));
> +  interp_add (interp_new (INTERP_MI3, NULL, mi_out_new (3), &procs, NULL));
>  
>    /* "mi" selects the most recent released version.  "mi2" was
>       released as part of GDB 6.0.  */
> -  interp_add (interp_new (INTERP_MI, NULL, mi_out_new (2), &procs));
> +  interp_add (interp_new (INTERP_MI, NULL, mi_out_new (stable_mi_versions[0]), &procs, mi_handshake));
>  }
> Index: tui/tui-interp.c
> ===================================================================
> RCS file: /cvs/src/src/gdb/tui/tui-interp.c,v
> retrieving revision 1.5
> diff -w -u -r1.5 tui-interp.c
> --- tui/tui-interp.c	7 Feb 2004 04:40:36 -0000	1.5
> +++ tui/tui-interp.c	4 Nov 2004 19:05:35 -0000
> @@ -198,7 +198,7 @@
>  
>    /* Create a default uiout builder for the TUI. */
>    tui_out = tui_out_new (gdb_stdout);
> -  interp_add (interp_new ("tui", NULL, tui_out, &procs));
> +  interp_add (interp_new ("tui", NULL, tui_out, &procs, NULL));
>    if (interpreter_p && strcmp (interpreter_p, "tui") == 0)
>      tui_start_enabled = 1;
>  

Re: MI handshaking

[Andrew Cagney]

(as is obvious, 6.3 is effectively out, I'm draining the queue)

Bob Rossi wrote:
> BTW, here is an example of how it looks,
> 
> $ ../../objdir3/gdb/gdb -i=mi
> mi_handshake={stable=mi2}
> ~"GNU gdb 6.3.50_2004-11-04-cvs\n"
> ~"Copyright 2004 Free Software Foundation, Inc.\n"
> ~"GDB is free software, covered by the GNU General Public License, and you are\n"
> ~"welcome to change it and/or distribute copies of it under certain conditions.\n"
> ~"Type \"show copying\" to see the conditions.\n"
> ~"There is absolutely no warranty for GDB.  Type \"show warranty\" for details.\n"
> ~"This GDB was configured as \"i686-pc-linux-gnu\"."
> ~"\n"
> (gdb)
> 
> I can obviously change the syntax of the output if it is desired.
> There should probably be a '~' or something like that, any suggestions?

Hmm, it's async (or unprompted), has the hypothetical potential for 
multiple values, and leaves us wondering which of those values it choose:

*mi-handshake={version=mi2,stable=[mi2]}

it should also appear after the copyright.

Oh and testing ;-)

Nick, Alain, comments?

Andrew

PS: I'd clean up the ChangeLogS a little, for instance:

      * interps.c (struct interp): add field, handshake

did you mean:

      * interps.c (struct interp): Add field "handshake".

?

> On Thu, Nov 04, 2004 at 02:57:01PM -0500, Bob Rossi wrote:
> 
>>Hi,
>>
>>Here is a simple patch that I think will make everyone happy. It allows
>>the MI to handshake with the front end.
>>
>>   * It prints all the stable MI versions ( currently only 1 )
>>   * If there is more than one stable version ( which there isn't ) it 
>>     let's the front end select the protocol to use.
>>
>>This happens only when the front end selects -i=mi, anything like -i=mi2
>>will go directly to mi2 without the output.
>>
>>The one question I have is, should the documentation for this be in the
>>MI output syntax? or should there me a new field called 
>>MI handshaking syntax?
>>
>>Thanks,
>>Bob Rossi
>>
>>     * interps.c (struct interp): add field, handshake
>>     (interp_new): Add parameter, handshake
>>     (interp_can_handshake,interp_handshake): add function definitions
>>     * interps.h (interp_handshake_ftype): add typedef
>>     (interp_new): Add parameter, handshake
>>     (interp_can_handshake,interp_handshake): add function prototype
>>     * main.c (captured_main): Add the handshaking code
>>     * cli/cli-interp.c (_initialize_cli_interp): changed interface to
>>     interp_new
>>     * mi/mi-interp.c (stable_mi_versions): add table of stable MI versions
>>     (mi_handshake): Add function to do handshaking
>>     (_initialize_mi_interp): changed interface to interp_new
>>     * tui/tui-interp.c (_initialize_tui_interp): changed interface to
>>     interp_new
>>
>>Index: interps.c
>>===================================================================
>>RCS file: /cvs/src/src/gdb/interps.c,v
>>retrieving revision 1.8
>>diff -w -u -r1.8 interps.c
>>--- interps.c	13 Sep 2004 18:26:30 -0000	1.8
>>+++ interps.c	4 Nov 2004 19:05:33 -0000
>>@@ -68,6 +68,8 @@
>> 
>>   const struct interp_procs *procs;
>>   int quiet_p;
>>+
>>+  interp_handshake_ftype *handshake;
>> };
>> 
>> /* Functions local to this file. */
>>@@ -90,7 +92,7 @@
>>    interpreter. */
>> struct interp *
>> interp_new (const char *name, void *data, struct ui_out *uiout,
>>-	    const struct interp_procs *procs)
>>+	    const struct interp_procs *procs, interp_handshake_ftype *handshake)
>> {
>>   struct interp *new_interp;
>> 
>>@@ -102,6 +104,7 @@
>>   new_interp->quiet_p = 0;
>>   new_interp->procs = procs;
>>   new_interp->inited = 0;
>>+  new_interp->handshake = handshake;
>> 
>>   return new_interp;
>> }
>>@@ -239,6 +242,22 @@
>>   return current_interpreter->interpreter_out;
>> }
>> 
>>+int
>>+interp_can_handshake (struct interp *interp)
>>+{
>>+  if (interp != NULL)
>>+    if (interp->handshake)
>>+      return 1;
>>+
>>+  return 0;
>>+}
>>+
>>+struct interp *
>>+interp_handshake (struct interp *interp) 
>>+{
>>+    return interp_lookup (interp->handshake (gdb_stdout, gdb_stdin));
>>+}
>>+
>> /* Returns true if the current interp is the passed in name. */
>> int
>> current_interp_named_p (const char *interp_name)
>>Index: interps.h
>>===================================================================
>>RCS file: /cvs/src/src/gdb/interps.h,v
>>retrieving revision 1.6
>>diff -w -u -r1.6 interps.h
>>--- interps.h	18 Feb 2004 19:01:36 -0000	1.6
>>+++ interps.h	4 Nov 2004 19:05:33 -0000
>>@@ -40,6 +40,7 @@
>> typedef int (interp_prompt_p_ftype) (void *data);
>> typedef int (interp_exec_ftype) (void *data, const char *command);
>> typedef void (interp_command_loop_ftype) (void *data);
>>+typedef const char *(interp_handshake_ftype) (struct ui_file *gdb_stdout, struct ui_file *gdb_stdin);
>> 
>> struct interp_procs
>> {
>>@@ -53,11 +54,14 @@
>> 
>> extern struct interp *interp_new (const char *name, void *data,
>> 				  struct ui_out *uiout,
>>-				  const struct interp_procs *procs);
>>+		const struct interp_procs *procs,
>>+		interp_handshake_ftype *handshake);
>> extern void interp_add (struct interp *interp);
>> extern int interp_set (struct interp *interp);
>> extern struct interp *interp_lookup (const char *name);
>> extern struct ui_out *interp_ui_out (struct interp *interp);
>>+extern int interp_can_handshake (struct interp *interp);
>>+extern struct interp *interp_handshake (struct interp *interp);
>> 
>> extern int current_interp_named_p (const char *name);
>> extern int current_interp_display_prompt_p (void);
>>Index: main.c
>>===================================================================
>>RCS file: /cvs/src/src/gdb/main.c,v
>>retrieving revision 1.44
>>diff -w -u -r1.44 main.c
>>--- main.c	10 Aug 2004 22:36:39 -0000	1.44
>>+++ main.c	4 Nov 2004 19:05:34 -0000
>>@@ -561,8 +561,13 @@
>>   {
>>     /* Find it.  */
>>     struct interp *interp = interp_lookup (interpreter_p);
>>+
>>+    if (interp && interp_can_handshake (interp))
>>+		interp = interp_handshake (interp);
>>+
>>     if (interp == NULL)
>>       error ("Interpreter `%s' unrecognized", interpreter_p);
>>+
>>     /* Install it.  */
>>     if (!interp_set (interp))
>>       {
>>Index: cli/cli-interp.c
>>===================================================================
>>RCS file: /cvs/src/src/gdb/cli/cli-interp.c,v
>>retrieving revision 1.4
>>diff -w -u -r1.4 cli-interp.c
>>--- cli/cli-interp.c	3 Jul 2003 14:49:26 -0000	1.4
>>+++ cli/cli-interp.c	4 Nov 2004 19:05:34 -0000
>>@@ -151,7 +151,7 @@
>> 
>>   /* Create a default uiout builder for the CLI. */
>>   cli_uiout = cli_out_new (gdb_stdout);
>>-  cli_interp = interp_new (INTERP_CONSOLE, NULL, cli_uiout, &procs);
>>+  cli_interp = interp_new (INTERP_CONSOLE, NULL, cli_uiout, &procs, NULL);
>> 
>>   interp_add (cli_interp);
>> }
>>Index: mi/mi-interp.c
>>===================================================================
>>RCS file: /cvs/src/src/gdb/mi/mi-interp.c,v
>>retrieving revision 1.11
>>diff -w -u -r1.11 mi-interp.c
>>--- mi/mi-interp.c	13 Sep 2004 18:26:31 -0000	1.11
>>+++ mi/mi-interp.c	4 Nov 2004 19:05:34 -0000
>>@@ -364,6 +364,66 @@
>>   start_event_loop ();
>> }
>> 
>>+/* The latest stable mi version that is being tested.
>>+   There could potentially be several versions of MI that are stable
>>+   at a time. */
>>+static const int stable_mi_versions[] = 
>>+{
>>+  2,
>>+  0
>>+};
>>+
>>+/* Allows MI and the front end to agree on an MI protocol.
>>+   
>>+   All of the stable MI versions are currently printed. If there is more
>>+   than one stable MI version, than it is expected the user will write
>>+   back the version they want to communicate with. 
>>+   
>>+   Returns the MI version string the user requested, or if there is only
>>+   one version, that string is returned. */
>>+static const char *mi_handshake (struct ui_file *gdb_stdout,
>>+	struct ui_file *gdb_stdin)
>>+{
>>+  static char mi_buf[32]; 
>>+  int i;
>>+
>>+  if (!gdb_stdout || !gdb_stdin)
>>+	  return NULL;
>>+
>>+  /* Output the header, can't use mi_out stuff because no mi has
>>+	 been chosen and initialized yet. */
>>+  fprintf_unfiltered ( gdb_stdout, "mi_handshake={" );
>>+
>>+  /* Output all the stable versions */
>>+  for (i = 0; stable_mi_versions[i] != 0; ++i ) 
>>+    {
>>+      if (i > 0)
>>+        fprintf_unfiltered (gdb_stdout, ",");
>>+
>>+        fprintf_unfiltered (gdb_stdout, "stable=mi%d", stable_mi_versions[i] );
>>+    }
>>+
>>+  fprintf_unfiltered ( gdb_stdout, "}\n" );
>>+	
>>+  /* If there was more than one stable version outputted, ask the front
>>+	 end which one it should use */
>>+  if ( i > 1 ) 
>>+  {
>>+    int size;
>>+	size = ui_file_read ( gdb_stdin, mi_buf, 31 );
>>+	mi_buf[size--] = 0; /* null terminate, and remove new line */
>>+	while ( size >= 0 && (mi_buf[size] == '\n' || mi_buf[size] == '\r') )
>>+      mi_buf[size--] = 0;
>>+
>>+	/* The mi option is not valid in this mode. */
>>+	if ( strcmp ( mi_buf, "mi" ) == 0 )
>>+      return NULL;
>>+  } else
>>+    sprintf ( mi_buf, "mi%d", stable_mi_versions[0] );
>>+
>>+  return mi_buf;
>>+}
>>+
>> extern initialize_file_ftype _initialize_mi_interp; /* -Wmissing-prototypes */
>> 
>> void
>>@@ -379,11 +439,11 @@
>>   };
>> 
>>   /* The various interpreter levels.  */
>>-  interp_add (interp_new (INTERP_MI1, NULL, mi_out_new (1), &procs));
>>-  interp_add (interp_new (INTERP_MI2, NULL, mi_out_new (2), &procs));
>>-  interp_add (interp_new (INTERP_MI3, NULL, mi_out_new (3), &procs));
>>+  interp_add (interp_new (INTERP_MI1, NULL, mi_out_new (1), &procs, NULL));
>>+  interp_add (interp_new (INTERP_MI2, NULL, mi_out_new (2), &procs, NULL));
>>+  interp_add (interp_new (INTERP_MI3, NULL, mi_out_new (3), &procs, NULL));
>> 
>>   /* "mi" selects the most recent released version.  "mi2" was
>>      released as part of GDB 6.0.  */
>>-  interp_add (interp_new (INTERP_MI, NULL, mi_out_new (2), &procs));
>>+  interp_add (interp_new (INTERP_MI, NULL, mi_out_new (stable_mi_versions[0]), &procs, mi_handshake));
>> }
>>Index: tui/tui-interp.c
>>===================================================================
>>RCS file: /cvs/src/src/gdb/tui/tui-interp.c,v
>>retrieving revision 1.5
>>diff -w -u -r1.5 tui-interp.c
>>--- tui/tui-interp.c	7 Feb 2004 04:40:36 -0000	1.5
>>+++ tui/tui-interp.c	4 Nov 2004 19:05:35 -0000
>>@@ -198,7 +198,7 @@
>> 
>>   /* Create a default uiout builder for the TUI. */
>>   tui_out = tui_out_new (gdb_stdout);
>>-  interp_add (interp_new ("tui", NULL, tui_out, &procs));
>>+  interp_add (interp_new ("tui", NULL, tui_out, &procs, NULL));
>>   if (interpreter_p && strcmp (interpreter_p, "tui") == 0)
>>     tui_start_enabled = 1;
>> 
> 
> 

Re: MI handshaking

[Alain Magloire]

> 
> (as is obvious, 6.3 is effectively out, I'm draining the queue)
> 
> Bob Rossi wrote:
> > BTW, here is an example of how it looks,
> > 
> > $ ../../objdir3/gdb/gdb -i=mi
> > mi_handshake={stable=mi2}
> > ~"GNU gdb 6.3.50_2004-11-04-cvs\n"
> > ~"Copyright 2004 Free Software Foundation, Inc.\n"
> > ~"GDB is free software, covered by the GNU General Public License, and you are\n"
> > ~"welcome to change it and/or distribute copies of it under certain conditions.\n"
> > ~"Type \"show copying\" to see the conditions.\n"
> > ~"There is absolutely no warranty for GDB.  Type \"show warranty\" for details.\n"
> > ~"This GDB was configured as \"i686-pc-linux-gnu\"."
> > ~"\n"
> > (gdb)
> > 
> > I can obviously change the syntax of the output if it is desired.
> > There should probably be a '~' or something like that, any suggestions?
> 
> Hmm, it's async (or unprompted), has the hypothetical potential for 
> multiple values, and leaves us wondering which of those values it choose:
> 
> *mi-handshake={version=mi2,stable=[mi2]}
> 
> it should also appear after the copyright.
> 
> Oh and testing ;-)
> 
> Nick, Alain, comments?
> 

Is it a good idea to make this an exec-async?  There is really no state changes.
Printing it in the console-stream long with the
gdb version should be enough.

But if async is desired, how about a notify-async instead.

=mi-handshake,versions=[mi1,mi2,mi3],stable=[mi2]

As the doc is saying, notify-async contains supplementary information
that the client should handle.

Note: did not look at the patch.

Re: MI handshaking

[Eli Zaretskii]

> Date: Thu, 4 Nov 2004 14:57:01 -0500
> From: Bob Rossi <bob@brasko.net>
> 
> The one question I have is, should the documentation for this be in the
> MI output syntax? or should there me a new field called 
> MI handshaking syntax?

I'd prefer a new subsection right at the beginning of the GDB/MI
description in the manual.  That way, someone who designs a front end
will see this stuff when she begins reading the docs.

Re: MI handshaking

[Bob Rossi]

On Thu, Nov 04, 2004 at 11:23:11PM +0200, Eli Zaretskii wrote:
> > Date: Thu, 4 Nov 2004 14:57:01 -0500
> > From: Bob Rossi <bob@brasko.net>
> > 
> > The one question I have is, should the documentation for this be in the
> > MI output syntax? or should there me a new field called 
> > MI handshaking syntax?
> 
> I'd prefer a new subsection right at the beginning of the GDB/MI
> description in the manual.  That way, someone who designs a front end
> will see this stuff when she begins reading the docs.

Here is the new patch, with the doco sections.

Does anyone care if the output of the handshaking starts with a special
char like '~' or something? Or should I leave it the way it is below?

$ ./gdb/gdb -i=mi
handshake={stable_protocols={mi2}}
~"GNU gdb 6.3.50_2004-11-05-cvs\n"
~"Copyright 2004 Free Software Foundation, Inc.\n"

Any suggestions?

Thanks,
Bob Rossi


Index: gdb/interps.c
===================================================================
RCS file: /cvs/src/src/gdb/interps.c,v
retrieving revision 1.8
diff -w -u -r1.8 interps.c
--- gdb/interps.c	13 Sep 2004 18:26:30 -0000	1.8
+++ gdb/interps.c	5 Nov 2004 16:36:28 -0000
@@ -68,6 +68,8 @@
 
   const struct interp_procs *procs;
   int quiet_p;
+
+  interp_handshake_ftype *handshake;
 };
 
 /* Functions local to this file. */
@@ -90,7 +92,7 @@
    interpreter. */
 struct interp *
 interp_new (const char *name, void *data, struct ui_out *uiout,
-	    const struct interp_procs *procs)
+	    const struct interp_procs *procs, interp_handshake_ftype *handshake)
 {
   struct interp *new_interp;
 
@@ -102,6 +104,7 @@
   new_interp->quiet_p = 0;
   new_interp->procs = procs;
   new_interp->inited = 0;
+  new_interp->handshake = handshake;
 
   return new_interp;
 }
@@ -239,6 +242,22 @@
   return current_interpreter->interpreter_out;
 }
 
+int
+interp_can_handshake (struct interp *interp)
+{
+  if (interp != NULL)
+    if (interp->handshake)
+      return 1;
+
+  return 0;
+}
+
+struct interp *
+interp_handshake (struct interp *interp) 
+{
+    return interp_lookup (interp->handshake (gdb_stdout, gdb_stdin));
+}
+
 /* Returns true if the current interp is the passed in name. */
 int
 current_interp_named_p (const char *interp_name)
Index: gdb/interps.h
===================================================================
RCS file: /cvs/src/src/gdb/interps.h,v
retrieving revision 1.6
diff -w -u -r1.6 interps.h
--- gdb/interps.h	18 Feb 2004 19:01:36 -0000	1.6
+++ gdb/interps.h	5 Nov 2004 16:36:28 -0000
@@ -40,6 +40,7 @@
 typedef int (interp_prompt_p_ftype) (void *data);
 typedef int (interp_exec_ftype) (void *data, const char *command);
 typedef void (interp_command_loop_ftype) (void *data);
+typedef const char *(interp_handshake_ftype) (struct ui_file *gdb_stdout, struct ui_file *gdb_stdin);
 
 struct interp_procs
 {
@@ -53,11 +54,14 @@
 
 extern struct interp *interp_new (const char *name, void *data,
 				  struct ui_out *uiout,
-				  const struct interp_procs *procs);
+		const struct interp_procs *procs,
+		interp_handshake_ftype *handshake);
 extern void interp_add (struct interp *interp);
 extern int interp_set (struct interp *interp);
 extern struct interp *interp_lookup (const char *name);
 extern struct ui_out *interp_ui_out (struct interp *interp);
+extern int interp_can_handshake (struct interp *interp);
+extern struct interp *interp_handshake (struct interp *interp);
 
 extern int current_interp_named_p (const char *name);
 extern int current_interp_display_prompt_p (void);
Index: gdb/main.c
===================================================================
RCS file: /cvs/src/src/gdb/main.c,v
retrieving revision 1.44
diff -w -u -r1.44 main.c
--- gdb/main.c	10 Aug 2004 22:36:39 -0000	1.44
+++ gdb/main.c	5 Nov 2004 16:36:28 -0000
@@ -561,8 +561,13 @@
   {
     /* Find it.  */
     struct interp *interp = interp_lookup (interpreter_p);
+
+    if (interp && interp_can_handshake (interp))
+		interp = interp_handshake (interp);
+
     if (interp == NULL)
       error ("Interpreter `%s' unrecognized", interpreter_p);
+
     /* Install it.  */
     if (!interp_set (interp))
       {
Index: gdb/cli/cli-interp.c
===================================================================
RCS file: /cvs/src/src/gdb/cli/cli-interp.c,v
retrieving revision 1.4
diff -w -u -r1.4 cli-interp.c
--- gdb/cli/cli-interp.c	3 Jul 2003 14:49:26 -0000	1.4
+++ gdb/cli/cli-interp.c	5 Nov 2004 16:36:29 -0000
@@ -151,7 +151,7 @@
 
   /* Create a default uiout builder for the CLI. */
   cli_uiout = cli_out_new (gdb_stdout);
-  cli_interp = interp_new (INTERP_CONSOLE, NULL, cli_uiout, &procs);
+  cli_interp = interp_new (INTERP_CONSOLE, NULL, cli_uiout, &procs, NULL);
 
   interp_add (cli_interp);
 }
Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.222
diff -w -u -r1.222 gdb.texinfo
--- gdb/doc/gdb.texinfo	23 Oct 2004 15:05:29 -0000	1.222
+++ gdb/doc/gdb.texinfo	5 Nov 2004 16:36:41 -0000
@@ -14997,6 +14997,7 @@
 @menu
 * GDB/MI Command Syntax::
 * GDB/MI Compatibility with CLI::
+* GDB/MI Handshaking Interface::
 * GDB/MI Output Records::
 * GDB/MI Command Description Format::
 * GDB/MI Breakpoint Table Commands::
@@ -15021,11 +15022,50 @@
 @section @sc{gdb/mi} Command Syntax
 
 @menu
+* GDB/MI Handshaking Syntax::
 * GDB/MI Input Syntax::
 * GDB/MI Output Syntax::
 * GDB/MI Simple Examples::
 @end menu
 
+@node GDB/MI Handshaking Syntax
+@subsection @sc{gdb/mi} Handshaking Syntax
+
+@cindex handshaking syntax for @sc{gdb/mi}
+@cindex @sc{gdb/mi}, handshaking syntax
+@table @code
+@item @var{handshake_output} @expansion{}
+@code{"handshake=@{stable_protocols=@{" @var{mi-protocol-list} 
+"@}" @var{nl}}
+
+@item @var{mi-protocol-list} @expansion{}
+@code{ epsilon | @var{mi-protocol} | @var{mi-protocol-list} "," @var{mi-protocol} }
+
+@item @var{mi-protocol} @expansion{}
+@code{ "mi" @var{token} }
+
+@item @var{token} @expansion{}
+"any sequence of digits"
+
+@item @var{nl} @expansion{}
+@code{CR | CR-LF}
+@end table
+
+@noindent
+Notes:
+
+@itemize @bullet
+@item
+If only one stable @sc{mi} protocol is supported by a particular release of 
+@value{GDBN}, then that release is used and the caller does not have to
+do anything.
+
+@item
+If there is more than one stable @sc{mi} protocol supported by a particular 
+release of @value{GDBN}, then the caller has to specify which version of the
+@sc{mi} protocol it wants @value{GDBN} to communicate with.
+@end itemize
+
 @node GDB/MI Input Syntax
 @subsection @sc{gdb/mi} Input Syntax
 
@@ -15111,6 +15151,9 @@
 @var{token}.
 
 @table @code
+@item @var{output-list} @expansion{}
+@code{@var{output} | @var{output-list} @var{output}}
+
 @item @var{output} @expansion{}
 @code{( @var{out-of-band-record} )* [ @var{result-record} ] "(@value{GDBP})" @var{nl}}
 
@@ -15314,6 +15357,38 @@
 an un-supported hybrid of @sc{gdb/mi} and CLI output.
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Handshaking Interface
+@section @sc{gdb/mi} Handshaking Interface
+
+@cindex @sc{gdb/mi}, handshaking interface
+@value{GDBN} is capable of speaking several MI protocols at a time.  This
+interface is intended to help developers understand what version of the MI
+protocol that a particular @value{GDBN} is going to communicate with.
+
+It is possible to start the @sc{gdb/mi} interpreter using -i=mi1, -i=mi2, or 
+simply with -i=mi.  If a front end starts @value{GDBN} with -i=miN it will 
+bypass the handshaking mode and will go directly into the version of the MI 
+that it requested.  However, if @value{GDBN} is started with the -i=mi flag,
+then this tells @value{GDBN} to go into it's handshaking mode with the 
+client to determine the correct MI protocol to communicate with.
+
+@value{GDBN} will output all of the stable versions of the MI protocol that
+it supports.  The term "stable MI protocol" simply means that the protocol
+was tested when this particular release was made.  Protocols that are no longer
+tested in the @value{GDBN} testsuite will not be considered a stable release.  
+If the caller still wishes to communicate with @value{GDBN} using one of these
+untested protocols, they could simply try to invoke @value{GDBN} with -i=miN,
+where N is version they wish to communicate with.
+
+@value{GDBN} will output all of the stable MI versions that it supports.  
+If a specific version of @value{GDBN} speaks only one stable MI protocol than
+it will begin communicating with that version of the protocol.  The front end
+has no way to change this version.  However, if @value{GDBN} speaks several 
+versions of the MI protocol, than it will output a list of these protocols 
+and the front end then has to choose the version that it wants @value{GDBN}
+to communicate with.
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Output Records
 @section @sc{gdb/mi} Output Records
 
Index: gdb/mi/mi-interp.c
===================================================================
RCS file: /cvs/src/src/gdb/mi/mi-interp.c,v
retrieving revision 1.11
diff -w -u -r1.11 mi-interp.c
--- gdb/mi/mi-interp.c	13 Sep 2004 18:26:31 -0000	1.11
+++ gdb/mi/mi-interp.c	5 Nov 2004 16:36:42 -0000
@@ -364,6 +364,66 @@
   start_event_loop ();
 }
 
+/* The latest stable mi version that is being tested.
+   There could potentially be several versions of MI that are stable
+   at a time. */
+static const int stable_mi_versions[] = 
+{
+  2,
+  0
+};
+
+/* Allows MI and the front end to agree on an MI protocol.
+   
+   All of the stable MI versions are currently printed. If there is more
+   than one stable MI version, than it is expected the user will write
+   back the version they want to communicate with. 
+   
+   Returns the MI version string the user requested, or if there is only
+   one version, that string is returned. */
+static const char *mi_handshake (struct ui_file *gdb_stdout,
+	struct ui_file *gdb_stdin)
+{
+  static char mi_buf[32]; 
+  int i;
+
+  if (!gdb_stdout || !gdb_stdin)
+	  return NULL;
+
+  /* Output the header, can't use mi_out stuff because no mi has
+	 been chosen and initialized yet. */
+  fprintf_unfiltered ( gdb_stdout, "handshake={stable_protocols={" );
+
+  /* Output all the stable versions */
+  for (i = 0; stable_mi_versions[i] != 0; ++i ) 
+    {
+      if (i > 0)
+        fprintf_unfiltered (gdb_stdout, ",");
+
+        fprintf_unfiltered (gdb_stdout, "mi%d", stable_mi_versions[i] );
+    }
+
+  fprintf_unfiltered ( gdb_stdout, "}}\n" );
+	
+  /* If there was more than one stable version outputted, ask the front
+	 end which one it should use */
+  if ( i > 1 ) 
+  {
+    int size;
+	size = ui_file_read ( gdb_stdin, mi_buf, 31 );
+	mi_buf[size--] = 0; /* null terminate, and remove new line */
+	while ( size >= 0 && (mi_buf[size] == '\n' || mi_buf[size] == '\r') )
+      mi_buf[size--] = 0;
+
+	/* The mi option is not valid in this mode. */
+	if ( strcmp ( mi_buf, "mi" ) == 0 )
+      return NULL;
+  } else
+    sprintf ( mi_buf, "mi%d", stable_mi_versions[0] );
+
+  return mi_buf;
+}
+
 extern initialize_file_ftype _initialize_mi_interp; /* -Wmissing-prototypes */
 
 void
@@ -379,11 +439,11 @@
   };
 
   /* The various interpreter levels.  */
-  interp_add (interp_new (INTERP_MI1, NULL, mi_out_new (1), &procs));
-  interp_add (interp_new (INTERP_MI2, NULL, mi_out_new (2), &procs));
-  interp_add (interp_new (INTERP_MI3, NULL, mi_out_new (3), &procs));
+  interp_add (interp_new (INTERP_MI1, NULL, mi_out_new (1), &procs, NULL));
+  interp_add (interp_new (INTERP_MI2, NULL, mi_out_new (2), &procs, NULL));
+  interp_add (interp_new (INTERP_MI3, NULL, mi_out_new (3), &procs, NULL));
 
   /* "mi" selects the most recent released version.  "mi2" was
      released as part of GDB 6.0.  */
-  interp_add (interp_new (INTERP_MI, NULL, mi_out_new (2), &procs));
+  interp_add (interp_new (INTERP_MI, NULL, mi_out_new (stable_mi_versions[0]), &procs, mi_handshake));
 }
Index: gdb/tui/tui-interp.c
===================================================================
RCS file: /cvs/src/src/gdb/tui/tui-interp.c,v
retrieving revision 1.5
diff -w -u -r1.5 tui-interp.c
--- gdb/tui/tui-interp.c	7 Feb 2004 04:40:36 -0000	1.5
+++ gdb/tui/tui-interp.c	5 Nov 2004 16:36:43 -0000
@@ -198,7 +198,7 @@
 
   /* Create a default uiout builder for the TUI. */
   tui_out = tui_out_new (gdb_stdout);
-  interp_add (interp_new ("tui", NULL, tui_out, &procs));
+  interp_add (interp_new ("tui", NULL, tui_out, &procs, NULL));
   if (interpreter_p && strcmp (interpreter_p, "tui") == 0)
     tui_start_enabled = 1;
 

Re: MI handshaking

[Eli Zaretskii]

> Date: Fri, 5 Nov 2004 11:39:33 -0500
> From: Bob Rossi <bob@brasko.net>
> Cc: gdb-patches@sources.redhat.com
> 
> +@node GDB/MI Handshaking Syntax
> +@subsection @sc{gdb/mi} Handshaking Syntax
> +
> +@cindex handshaking syntax for @sc{gdb/mi}
> +@cindex @sc{gdb/mi}, handshaking syntax
> +@table @code
> +@item @var{handshake_output} @expansion{}
> +@code{"handshake=@{stable_protocols=@{" @var{mi-protocol-list} 
> +"@}" @var{nl}}

I think there's a need here for a cross-reference to the section that
explains the reason and principles of the handshaking (the other
section you wrote), otherwise this table looks awkwardly unexplained.

> +It is possible to start the @sc{gdb/mi} interpreter using -i=mi1, -i=mi2, or 
> +simply with -i=mi.

The command-line options should be in @samp{} or in @option{}, like
this:

  It is possible to start the @sc{gdb/mi} interpreter using @samp{-i=mi1}

Actually, instead of using literal mi1 and mi2, which could confuse
the reader into thinking that only MI1 and MI2 are supported (think
about someone reading this 10 years from now), I'd say

  It is possible to start the @sc{gdb/mi} interpreter using
  @samp{-i=mi@var{n}}, where @var{n} is the MI protocol version
  (@pxref{Interpreters}).  When invoked with a specific version of the
  MI interpreter, @value{GDBN} will bypass the handshaking mode and go
  directly into...

> +then this tells @value{GDBN} to go into it's handshaking mode with the 
                                           ^^^^
This should be "its", without the apostrophe.

> +it supports.  The term "stable MI protocol" simply means that the protocol

Please use ``this style'' to quote phrases in Texinfo (the result is
prettier in the printed version).  Actually, in this case, since you
are introducing a new term, I'd suggest to say

  The term @dfn{stable MI protocol} simply means...

Also, a @cindex entry here about stable MI protocol would be useful.

> +untested protocols, they could simply try to invoke @value{GDBN} with -i=miN,
> +where N is version they wish to communicate with.

Please use @var{n} instead of a literal "N" here.

> +If a specific version of @value{GDBN} speaks only one stable MI protocol than

The last woprd should be "then", not "than".

> +versions of the MI protocol, than it will output a list of these protocols 
                                ^^^^
Again, "then".

Other than these few minor problems, the documentation patch is
approved.  Thanks.

Re: MI handshaking

[Bob Rossi]

On Fri, Nov 05, 2004 at 07:44:18PM +0200, Eli Zaretskii wrote:
> > Date: Fri, 5 Nov 2004 11:39:33 -0500
> > From: Bob Rossi <bob@brasko.net>
> > Cc: gdb-patches@sources.redhat.com
> > 
> > +@node GDB/MI Handshaking Syntax
> > +@subsection @sc{gdb/mi} Handshaking Syntax
> > +
> > +@cindex handshaking syntax for @sc{gdb/mi}
> > +@cindex @sc{gdb/mi}, handshaking syntax
> > +@table @code
> > +@item @var{handshake_output} @expansion{}
> > +@code{"handshake=@{stable_protocols=@{" @var{mi-protocol-list} 
> > +"@}" @var{nl}}
> 
> I think there's a need here for a cross-reference to the section that
> explains the reason and principles of the handshaking (the other
> section you wrote), otherwise this table looks awkwardly unexplained.

I think i did this correctly.
> > +It is possible to start the @sc{gdb/mi} interpreter using -i=mi1, -i=mi2, or 
> > +simply with -i=mi.
> 
> The command-line options should be in @samp{} or in @option{}, like
> this:
> 
>   It is possible to start the @sc{gdb/mi} interpreter using @samp{-i=mi1}

done
> 
> Actually, instead of using literal mi1 and mi2, which could confuse
> the reader into thinking that only MI1 and MI2 are supported (think
> about someone reading this 10 years from now), I'd say
> 
>   It is possible to start the @sc{gdb/mi} interpreter using
>   @samp{-i=mi@var{n}}, where @var{n} is the MI protocol version
>   (@pxref{Interpreters}).  When invoked with a specific version of the
>   MI interpreter, @value{GDBN} will bypass the handshaking mode and go
>   directly into...

done
> 
> > +then this tells @value{GDBN} to go into it's handshaking mode with the 
>                                            ^^^^
> This should be "its", without the apostrophe.
> 

done
> > +it supports.  The term "stable MI protocol" simply means that the protocol
> 
> Please use ``this style'' to quote phrases in Texinfo (the result is
> prettier in the printed version).  Actually, in this case, since you
> are introducing a new term, I'd suggest to say
> 
>   The term @dfn{stable MI protocol} simply means...
> 
> Also, a @cindex entry here about stable MI protocol would be useful.
> 

I think I did the cindex part right, but I don't really understand how
there used, or why.
> > +untested protocols, they could simply try to invoke @value{GDBN} with -i=miN,
> > +where N is version they wish to communicate with.
> 
> Please use @var{n} instead of a literal "N" here.
> 
> > +If a specific version of @value{GDBN} speaks only one stable MI protocol than
> 
> The last woprd should be "then", not "than".
> 

done
> > +versions of the MI protocol, than it will output a list of these protocols 
>                                 ^^^^
> Again, "then".
> 

done
> Other than these few minor problems, the documentation patch is
> approved.  Thanks.

I hope this resolves all of the issues you brought up. I really am not
good at editing info files but am trying to do my best to help out.

Bob Rossi

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.222
diff -w -u -r1.222 gdb.texinfo
--- gdb.texinfo	23 Oct 2004 15:05:29 -0000	1.222
+++ gdb.texinfo	5 Nov 2004 22:09:54 -0000
@@ -14997,6 +14997,7 @@
 @menu
 * GDB/MI Command Syntax::
 * GDB/MI Compatibility with CLI::
+* GDB/MI Handshaking Interface::
 * GDB/MI Output Records::
 * GDB/MI Command Description Format::
 * GDB/MI Breakpoint Table Commands::
@@ -15021,11 +15022,53 @@
 @section @sc{gdb/mi} Command Syntax
 
 @menu
+* GDB/MI Handshaking Syntax::
 * GDB/MI Input Syntax::
 * GDB/MI Output Syntax::
 * GDB/MI Simple Examples::
 @end menu
 
+@node GDB/MI Handshaking Syntax
+@subsection @sc{gdb/mi} Handshaking Syntax
+
+@cindex handshaking syntax for @sc{gdb/mi}
+@cindex @sc{gdb/mi}, handshaking syntax
+@table @code
+@item @var{handshake_output} @expansion{}
+@code{"handshake=@{stable_protocols=@{" @var{mi-protocol-list} 
+"@}" @var{nl}}
+
+@item @var{mi-protocol-list} @expansion{}
+@code{ epsilon | @var{mi-protocol} | @var{mi-protocol-list} "," @var{mi-protocol} }
+
+@item @var{mi-protocol} @expansion{}
+@code{ "mi" @var{token} }
+
+@item @var{token} @expansion{}
+"any sequence of digits"
+
+@item @var{nl} @expansion{}
+@code{CR | CR-LF}
+@end table
+
+@noindent
+Notes:
+
+@itemize @bullet
+@item
+If only one stable @sc{mi} protocol is supported by a particular release of 
+@value{GDBN}, then that release is used and the caller does not have to
+do anything.
+
+@item
+If there is more than one stable @sc{mi} protocol supported by a particular 
+release of @value{GDBN}, then the caller has to specify which version of the
+@sc{mi} protocol it wants @value{GDBN} to communicate with.
+
+@item
+For more information on handshaking see @ref{GDB/MI Handshaking Interface}
+@end itemize
+
 @node GDB/MI Input Syntax
 @subsection @sc{gdb/mi} Input Syntax
 
@@ -15111,6 +15154,9 @@
 @var{token}.
 
 @table @code
+@item @var{output-list} @expansion{}
+@code{@var{output} | @var{output-list} @var{output}}
+
 @item @var{output} @expansion{}
 @code{( @var{out-of-band-record} )* [ @var{result-record} ] "(@value{GDBP})" @var{nl}}
 
@@ -15314,6 +15360,51 @@
 an un-supported hybrid of @sc{gdb/mi} and CLI output.
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Handshaking Interface
+@section @sc{gdb/mi} Handshaking Interface
+
+@cindex @sc{gdb/mi}, handshaking interface
+@value{GDBN} is capable of speaking several MI protocols at a time.  This
+interface is intended to help developers understand what version of the MI
+protocol that a particular @value{GDBN} is going to communicate with.
+
+It is possible to start the @sc{gdb/mi} interpreter using @samp{-i=mi@var{n}}, 
+where @var{n} is the MI protocol version (@pxref{Interpreters}).  When invoked 
+with a specific version of the MI interpreter, @value{GDBN} will bypass the 
+handshaking mode and go directly into the version of the MI that it requested.  
+However, if @value{GDBN} is started with the -i=mi flag, then this tells 
+@value{GDBN} to go into its handshaking mode with the client to determine the 
+correct MI protocol to communicate with.
+
+@value{GDBN} will output all of the stable versions of the MI protocol that
+it supports.  The term @dfn{stable MI protocol} simply means that the protocol
+was tested when this particular release was made.  Protocols that are no longer
+tested in the @value{GDBN} testsuite will not be considered a stable release.  
+If the caller still wishes to communicate with @value{GDBN} using one of these
+untested protocols, they could simply try to invoke @value{GDBN} with 
+-i=mi@var{N}, where @var{N} is version they wish to communicate with.
+
+@value{GDBN} will output all of the stable MI versions that it supports.  
+If a specific version of @value{GDBN} speaks only one stable MI protocol then
+it will begin communicating with that version of the protocol.  The front end
+has no way to change this version.  However, if @value{GDBN} speaks several 
+versions of the MI protocol, then it will output a list of these protocols 
+and the front end then has to choose the version that it wants @value{GDBN}
+to communicate with.
+
+@cindex @dfn{stable MI protocol}
+You could have a @value{GDBN} version that is capable of communicating with
+several versions of the @sc{mi} protocol.  In general, an official release or
+a CVS snapshot will have depricated @sc{mi} protocols, stable @sc{mi} 
+protocols and development @sc{mi} protocols.  The depricated @sc{mi} protocols
+are kept around in @value{GDBN} for some period of time and then will 
+eventually get removed.  The @dfn{stable MI protocols} are considered stable
+because they were tested when the particular @value{GDBN} program you have was
+created.  The development @sc{mi} protocols are not ready to be used since
+there is a good change there will be incompatible changes made to it before it
+can become a stable protocol.
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Output Records
 @section @sc{gdb/mi} Output Records
 

Re: MI handshaking

[Eli Zaretskii]

> Date: Fri, 5 Nov 2004 17:12:22 -0500
> From: Bob Rossi <bob@brasko.net>
> Cc: gdb-patches@sources.redhat.com
> 
> I really am not good at editing info files but am trying to do my
> best to help out.

You are doing a good job, although I have a few more minor comments,
see below.

The @cindex lines are collected by the program that generates the Info
files and put into the "Index" node.  Thereafter, you can use the `i'
command in the Info readers to quickly find stuff in the manual; that
command works by searching the string you type in the index.  This is
the most efficient means of using the manual as a reference, when you
know something is in the manual and need a fast way of finding it.

If you want to learn more about Texinfo, I suggest to read the manual
that comes with the Texinfo package.

> +@item
> +For more information on handshaking see @ref{GDB/MI Handshaking Interface}
> +@end itemize

Don't make this an @item (just a simple sentence that goes after @end
itemize), and make sure there's a period or comma after the closing
brace of @ref{...}.

> +However, if @value{GDBN} is started with the -i=mi flag, then this tells 

The "-i=mi" part should be in @samp{}.

> +untested protocols, they could simply try to invoke @value{GDBN} with 
> +-i=mi@var{N}, where @var{N} is version they wish to communicate with.

Same here.  And please don't use caps inside @var{}, as they look ugly
in print.

> +@cindex @dfn{stable MI protocol}

No need for @dfn in the index entries.

> +a CVS snapshot will have depricated @sc{mi} protocols, stable @sc{mi} 
                            ^^^^^^^^^^
"deprecated"

> +protocols and development @sc{mi} protocols.  The depricated @sc{mi} protocols
                                                     ^^^^^^^^^^
Same here.

> +eventually get removed.  The @dfn{stable MI protocols} are considered stable

@dfn should be used only once, the first time you introduce the term.
After that, simply use the term without any markup or quoting.

Re: MI handshaking

[Bob Rossi]

On Sat, Nov 06, 2004 at 12:07:07PM +0200, Eli Zaretskii wrote:
> > Date: Fri, 5 Nov 2004 17:12:22 -0500
> > From: Bob Rossi <bob@brasko.net>
> > Cc: gdb-patches@sources.redhat.com
> > 
> > I really am not good at editing info files but am trying to do my
> > best to help out.
> 
> You are doing a good job, although I have a few more minor comments,
> see below.
> 

OK, all the issues should be resolved. Here is a final patch with the
doco changes. Thanks for the speedy reply Eli.

Does anyone want to approve the code part of this patch? Any suggestions
on how to make it better?

Again the output looks like this,

$ gdb -i=mi
handshake={stable_protocols={mi2}}
~"GNU gdb 6.3.50_2004-11-08-cvs\n"

Would it be better to have a special char at the beggining? and put the
whole thing in quotes? 

I think it's good the way it is, because it's not actually in MI mode.

Thanks,
Bob Rossi

+	* interps.c (struct interp): add field, handshake
+	(interp_new): Add parameter, handshake
+	(interp_can_handshake,interp_handshake): add function definitions
+	* interps.h (interp_handshake_ftype): add typedef
+	(interp_new): Add parameter, handshake
+	(interp_can_handshake,interp_handshake): add function prototype
+	* main.c (captured_main): Add the handshaking code
+	* cli/cli-interp.c (_initialize_cli_interp): changed interface to
+	interp_new
+	* mi/mi-interp.c (stable_mi_versions): add table of stable MI versions
+	(mi_handshake): Add function to do handshaking
+	(_initialize_mi_interp): changed interface to interp_new
+	* tui/tui-interp.c (_initialize_tui_interp): changed interface to
+	interp_new

+    * gdb.texinfo (MI menu): Add 'GDB/MI Handshaking Interface'
+	(GDB/MI Command Syntax menu): Add 'GDB/MI Handshaking Syntax'
+	(GDB/MI Handshaking Syntax): Add new node
+	(GDB/MI Handshaking Interface): Add new node

Index: gdb/interps.c
===================================================================
RCS file: /cvs/src/src/gdb/interps.c,v
retrieving revision 1.8
diff -w -u -r1.8 interps.c
--- gdb/interps.c	13 Sep 2004 18:26:30 -0000	1.8
+++ gdb/interps.c	8 Nov 2004 14:43:07 -0000
@@ -68,6 +68,8 @@
 
   const struct interp_procs *procs;
   int quiet_p;
+
+  interp_handshake_ftype *handshake;
 };
 
 /* Functions local to this file. */
@@ -90,7 +92,7 @@
    interpreter. */
 struct interp *
 interp_new (const char *name, void *data, struct ui_out *uiout,
-	    const struct interp_procs *procs)
+	    const struct interp_procs *procs, interp_handshake_ftype *handshake)
 {
   struct interp *new_interp;
 
@@ -102,6 +104,7 @@
   new_interp->quiet_p = 0;
   new_interp->procs = procs;
   new_interp->inited = 0;
+  new_interp->handshake = handshake;
 
   return new_interp;
 }
@@ -239,6 +242,22 @@
   return current_interpreter->interpreter_out;
 }
 
+int
+interp_can_handshake (struct interp *interp)
+{
+  if (interp != NULL)
+    if (interp->handshake)
+      return 1;
+
+  return 0;
+}
+
+struct interp *
+interp_handshake (struct interp *interp) 
+{
+    return interp_lookup (interp->handshake (gdb_stdout, gdb_stdin));
+}
+
 /* Returns true if the current interp is the passed in name. */
 int
 current_interp_named_p (const char *interp_name)
Index: gdb/interps.h
===================================================================
RCS file: /cvs/src/src/gdb/interps.h,v
retrieving revision 1.6
diff -w -u -r1.6 interps.h
--- gdb/interps.h	18 Feb 2004 19:01:36 -0000	1.6
+++ gdb/interps.h	8 Nov 2004 14:43:07 -0000
@@ -40,6 +40,7 @@
 typedef int (interp_prompt_p_ftype) (void *data);
 typedef int (interp_exec_ftype) (void *data, const char *command);
 typedef void (interp_command_loop_ftype) (void *data);
+typedef const char *(interp_handshake_ftype) (struct ui_file *gdb_stdout, struct ui_file *gdb_stdin);
 
 struct interp_procs
 {
@@ -53,11 +54,14 @@
 
 extern struct interp *interp_new (const char *name, void *data,
 				  struct ui_out *uiout,
-				  const struct interp_procs *procs);
+		const struct interp_procs *procs,
+		interp_handshake_ftype *handshake);
 extern void interp_add (struct interp *interp);
 extern int interp_set (struct interp *interp);
 extern struct interp *interp_lookup (const char *name);
 extern struct ui_out *interp_ui_out (struct interp *interp);
+extern int interp_can_handshake (struct interp *interp);
+extern struct interp *interp_handshake (struct interp *interp);
 
 extern int current_interp_named_p (const char *name);
 extern int current_interp_display_prompt_p (void);
Index: gdb/main.c
===================================================================
RCS file: /cvs/src/src/gdb/main.c,v
retrieving revision 1.44
diff -w -u -r1.44 main.c
--- gdb/main.c	10 Aug 2004 22:36:39 -0000	1.44
+++ gdb/main.c	8 Nov 2004 14:43:07 -0000
@@ -561,8 +561,13 @@
   {
     /* Find it.  */
     struct interp *interp = interp_lookup (interpreter_p);
+
+    if (interp && interp_can_handshake (interp))
+		interp = interp_handshake (interp);
+
     if (interp == NULL)
       error ("Interpreter `%s' unrecognized", interpreter_p);
+
     /* Install it.  */
     if (!interp_set (interp))
       {
Index: gdb/cli/cli-interp.c
===================================================================
RCS file: /cvs/src/src/gdb/cli/cli-interp.c,v
retrieving revision 1.4
diff -w -u -r1.4 cli-interp.c
--- gdb/cli/cli-interp.c	3 Jul 2003 14:49:26 -0000	1.4
+++ gdb/cli/cli-interp.c	8 Nov 2004 14:43:08 -0000
@@ -151,7 +151,7 @@
 
   /* Create a default uiout builder for the CLI. */
   cli_uiout = cli_out_new (gdb_stdout);
-  cli_interp = interp_new (INTERP_CONSOLE, NULL, cli_uiout, &procs);
+  cli_interp = interp_new (INTERP_CONSOLE, NULL, cli_uiout, &procs, NULL);
 
   interp_add (cli_interp);
 }
Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.222
diff -w -u -r1.222 gdb.texinfo
--- gdb/doc/gdb.texinfo	23 Oct 2004 15:05:29 -0000	1.222
+++ gdb/doc/gdb.texinfo	8 Nov 2004 14:43:22 -0000
@@ -14997,6 +14997,7 @@
 @menu
 * GDB/MI Command Syntax::
 * GDB/MI Compatibility with CLI::
+* GDB/MI Handshaking Interface::
 * GDB/MI Output Records::
 * GDB/MI Command Description Format::
 * GDB/MI Breakpoint Table Commands::
@@ -15021,11 +15022,53 @@
 @section @sc{gdb/mi} Command Syntax
 
 @menu
+* GDB/MI Handshaking Syntax::
 * GDB/MI Input Syntax::
 * GDB/MI Output Syntax::
 * GDB/MI Simple Examples::
 @end menu
 
+@node GDB/MI Handshaking Syntax
+@subsection @sc{gdb/mi} Handshaking Syntax
+
+@cindex handshaking syntax for @sc{gdb/mi}
+@cindex @sc{gdb/mi}, handshaking syntax
+@table @code
+@item @var{handshake_output} @expansion{}
+@code{"handshake=@{stable_protocols=@{" @var{mi-protocol-list} 
+"@}" @var{nl}}
+
+@item @var{mi-protocol-list} @expansion{}
+@code{ epsilon | @var{mi-protocol} | @var{mi-protocol-list} "," @var{mi-protocol} }
+
+@item @var{mi-protocol} @expansion{}
+@code{ "mi" @var{token} }
+
+@item @var{token} @expansion{}
+"any sequence of digits"
+
+@item @var{nl} @expansion{}
+@code{CR | CR-LF}
+@end table
+
+@noindent
+Notes:
+
+@itemize @bullet
+@item
+If only one stable @sc{mi} protocol is supported by a particular release of 
+@value{GDBN}, then that release is used and the caller does not have to
+do anything.
+
+@item
+If there is more than one stable @sc{mi} protocol supported by a particular 
+release of @value{GDBN}, then the caller has to specify which version of the
+@sc{mi} protocol it wants @value{GDBN} to communicate with.
+
+@end itemize
+
+For more information on handshaking see @ref{GDB/MI Handshaking Interface}.
+
 @node GDB/MI Input Syntax
 @subsection @sc{gdb/mi} Input Syntax
 
@@ -15314,6 +15357,51 @@
 an un-supported hybrid of @sc{gdb/mi} and CLI output.
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Handshaking Interface
+@section @sc{gdb/mi} Handshaking Interface
+
+@cindex @sc{gdb/mi}, handshaking interface
+@value{GDBN} is capable of speaking several MI protocols at a time.  This
+interface is intended to help developers understand what version of the MI
+protocol that a particular @value{GDBN} is going to communicate with.
+
+It is possible to start the @sc{gdb/mi} interpreter using @samp{-i=mi@var{n}}, 
+where @var{n} is the MI protocol version (@pxref{Interpreters}).  When invoked 
+with a specific version of the MI interpreter, @value{GDBN} will bypass the 
+handshaking mode and go directly into the version of the MI that it requested.  
+However, if @value{GDBN} is started with the @samp{-i=mi} flag, then this tells 
+@value{GDBN} to go into its handshaking mode with the client to determine the 
+correct MI protocol to communicate with.
+
+@value{GDBN} will output all of the stable versions of the MI protocol that
+it supports.  The term @dfn{stable MI protocol} simply means that the protocol
+was tested when this particular release was made.  Protocols that are no longer
+tested in the @value{GDBN} testsuite will not be considered a stable release.  
+If the caller still wishes to communicate with @value{GDBN} using one of these
+untested protocols, they could simply try to invoke @value{GDBN} with 
+@samp{-i=mi@var{n}}, where @var{n} is version they wish to communicate with.
+
+@value{GDBN} will output all of the stable MI versions that it supports.  
+If a specific version of @value{GDBN} speaks only one stable MI protocol then
+it will begin communicating with that version of the protocol.  The front end
+has no way to change this version.  However, if @value{GDBN} speaks several 
+versions of the MI protocol, then it will output a list of these protocols 
+and the front end then has to choose the version that it wants @value{GDBN}
+to communicate with.
+
+@cindex stable MI protocol
+You could have a @value{GDBN} version that is capable of communicating with
+several versions of the @sc{mi} protocol.  In general, an official release or
+a CVS snapshot will have deprecated @sc{mi} protocols, stable @sc{mi} 
+protocols and development @sc{mi} protocols.  The deprecated @sc{mi} protocols
+are kept around in @value{GDBN} for some period of time and then will 
+eventually get removed.  The stable MI protocols are considered stable
+because they were tested when the particular @value{GDBN} program you have was
+created.  The development @sc{mi} protocols are not ready to be used since
+there is a good change there will be incompatible changes made to it before it
+can become a stable protocol.
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Output Records
 @section @sc{gdb/mi} Output Records
 
Index: gdb/mi/mi-interp.c
===================================================================
RCS file: /cvs/src/src/gdb/mi/mi-interp.c,v
retrieving revision 1.11
diff -w -u -r1.11 mi-interp.c
--- gdb/mi/mi-interp.c	13 Sep 2004 18:26:31 -0000	1.11
+++ gdb/mi/mi-interp.c	8 Nov 2004 14:43:22 -0000
@@ -364,6 +364,66 @@
   start_event_loop ();
 }
 
+/* The latest stable mi version that is being tested.
+   There could potentially be several versions of MI that are stable
+   at a time. */
+static const int stable_mi_versions[] = 
+{
+  2,
+  0
+};
+
+/* Allows MI and the front end to agree on an MI protocol.
+   
+   All of the stable MI versions are currently printed. If there is more
+   than one stable MI version, than it is expected the user will write
+   back the version they want to communicate with. 
+   
+   Returns the MI version string the user requested, or if there is only
+   one version, that string is returned. */
+static const char *mi_handshake (struct ui_file *gdb_stdout,
+	struct ui_file *gdb_stdin)
+{
+  static char mi_buf[32]; 
+  int i;
+
+  if (!gdb_stdout || !gdb_stdin)
+	  return NULL;
+
+  /* Output the header, can't use mi_out stuff because no mi has
+	 been chosen and initialized yet. */
+  fprintf_unfiltered ( gdb_stdout, "handshake={stable_protocols={" );
+
+  /* Output all the stable versions */
+  for (i = 0; stable_mi_versions[i] != 0; ++i ) 
+    {
+      if (i > 0)
+        fprintf_unfiltered (gdb_stdout, ",");
+
+        fprintf_unfiltered (gdb_stdout, "mi%d", stable_mi_versions[i] );
+    }
+
+  fprintf_unfiltered ( gdb_stdout, "}}\n" );
+	
+  /* If there was more than one stable version outputted, ask the front
+	 end which one it should use */
+  if ( i > 1 ) 
+  {
+    int size;
+	size = ui_file_read ( gdb_stdin, mi_buf, 31 );
+	mi_buf[size--] = 0; /* null terminate, and remove new line */
+	while ( size >= 0 && (mi_buf[size] == '\n' || mi_buf[size] == '\r') )
+      mi_buf[size--] = 0;
+
+	/* The mi option is not valid in this mode. */
+	if ( strcmp ( mi_buf, "mi" ) == 0 )
+      return NULL;
+  } else
+    sprintf ( mi_buf, "mi%d", stable_mi_versions[0] );
+
+  return mi_buf;
+}
+
 extern initialize_file_ftype _initialize_mi_interp; /* -Wmissing-prototypes */
 
 void
@@ -379,11 +439,11 @@
   };
 
   /* The various interpreter levels.  */
-  interp_add (interp_new (INTERP_MI1, NULL, mi_out_new (1), &procs));
-  interp_add (interp_new (INTERP_MI2, NULL, mi_out_new (2), &procs));
-  interp_add (interp_new (INTERP_MI3, NULL, mi_out_new (3), &procs));
+  interp_add (interp_new (INTERP_MI1, NULL, mi_out_new (1), &procs, NULL));
+  interp_add (interp_new (INTERP_MI2, NULL, mi_out_new (2), &procs, NULL));
+  interp_add (interp_new (INTERP_MI3, NULL, mi_out_new (3), &procs, NULL));
 
   /* "mi" selects the most recent released version.  "mi2" was
      released as part of GDB 6.0.  */
-  interp_add (interp_new (INTERP_MI, NULL, mi_out_new (2), &procs));
+  interp_add (interp_new (INTERP_MI, NULL, mi_out_new (stable_mi_versions[0]), &procs, mi_handshake));
 }
Index: gdb/tui/tui-interp.c
===================================================================
RCS file: /cvs/src/src/gdb/tui/tui-interp.c,v
retrieving revision 1.5
diff -w -u -r1.5 tui-interp.c
--- gdb/tui/tui-interp.c	7 Feb 2004 04:40:36 -0000	1.5
+++ gdb/tui/tui-interp.c	8 Nov 2004 14:43:23 -0000
@@ -198,7 +198,7 @@
 
   /* Create a default uiout builder for the TUI. */
   tui_out = tui_out_new (gdb_stdout);
-  interp_add (interp_new ("tui", NULL, tui_out, &procs));
+  interp_add (interp_new ("tui", NULL, tui_out, &procs, NULL));
   if (interpreter_p && strcmp (interpreter_p, "tui") == 0)
     tui_start_enabled = 1;
 

Re: MI handshaking

[Eli Zaretskii]

> Date: Mon, 8 Nov 2004 09:48:48 -0500
> From: Bob Rossi <bob@brasko.net>
> Cc: gdb-patches@sources.redhat.com
> 
> OK, all the issues should be resolved. Here is a final patch with the
> doco changes. Thanks for the speedy reply Eli.

Yes, fine as far as the doco part goes.

Re: MI handshaking

[Nick Roberts]

I've moved and can't pick up mail from uklinux anymore (see the MAINTAINERS
file).

> Hmm, it's async (or unprompted), has the hypothetical potential for multiple values, and leaves us wondering which of those values it choose:

> *mi-handshake={version=mi2,stable=[mi2]}

> it should also appear after the copyright.

> Oh and testing ;-)

> Nick, Alain, comments?

mi-handshake={version="mi2",protocols=[{name="mi2"}]} ?

Shouldn't this be output with ui_out_field_stream etc, rather than
fprintf_unfiltered? That presumably imposes some syntax on the output.

I have to say all this is a bit too hypothetical for me, at the moment. I
don't have the resources to track different MI versions. My priority is just
to get something working. If things pick up, I might be a bit picky later.
Hopefully, by then, others will be involved.

Nick

Re: MI handshaking

[Andrew Cagney]

Alain Magloire wrote:
>>(as is obvious, 6.3 is effectively out, I'm draining the queue)
>>
>>Bob Rossi wrote:
>>
>>>BTW, here is an example of how it looks,
>>>
>>>$ ../../objdir3/gdb/gdb -i=mi
>>>mi_handshake={stable=mi2}
>>>~"GNU gdb 6.3.50_2004-11-04-cvs\n"
>>>~"Copyright 2004 Free Software Foundation, Inc.\n"
>>>~"GDB is free software, covered by the GNU General Public License, and you are\n"
>>>~"welcome to change it and/or distribute copies of it under certain conditions.\n"
>>>~"Type \"show copying\" to see the conditions.\n"
>>>~"There is absolutely no warranty for GDB.  Type \"show warranty\" for details.\n"
>>>~"This GDB was configured as \"i686-pc-linux-gnu\"."
>>>~"\n"
>>>(gdb)
>>>
>>>I can obviously change the syntax of the output if it is desired.
>>>There should probably be a '~' or something like that, any suggestions?
>>
>>Hmm, it's async (or unprompted), has the hypothetical potential for 
>>multiple values, and leaves us wondering which of those values it choose:
>>
>>*mi-handshake={version=mi2,stable=[mi2]}
>>
>>it should also appear after the copyright.
>>
>>Oh and testing ;-)
>>
>>Nick, Alain, comments?
>>
> 
> 
> Is it a good idea to make this an exec-async?  There is really no state changes.
> Printing it in the console-stream long with the
> gdb version should be enough.
> 
> But if async is desired, how about a notify-async instead.
> 
> =mi-handshake,versions=[mi1,mi2,mi3],stable=[mi2]

Yes, thanks for the correction with ``=''.   But not 
``versions=[mi1,mi2,mi3]'' that's too much and misleading information.

I think the objective here needs to be to provide as much information as 
possible about what version of GDB and MI is running.  Hence the:

	version="mi2"

(where hopefully VERSION version is a member of STABLE :-) although 
strictly speaking it should probably be:

	mi-version="mi2"

just in case there's later a gdb-version="6.3.50" etc.

Andrew

> As the doc is saying, notify-async contains supplementary information
> that the client should handle.
> 
> Note: did not look at the patch.

Re: MI handshaking

[Eli Zaretskii]

> Date: Fri, 12 Nov 2004 17:57:30 -0500
> From: Andrew Cagney <cagney@gnu.org>
> Cc: Bob Rossi <bob@brasko.net>, Nick Roberts <nick@nick.uklinux.net>,
>         gdb-patches@sources.redhat.com
> 
> > =mi-handshake,versions=[mi1,mi2,mi3],stable=[mi2]
> 
> Yes, thanks for the correction with ``=''.   But not 
> ``versions=[mi1,mi2,mi3]'' that's too much and misleading information.
> 
> I think the objective here needs to be to provide as much information as 
> possible about what version of GDB and MI is running.  Hence the:
> 
> 	version="mi2"
> 
> (where hopefully VERSION version is a member of STABLE :-)

We've been through this discussion, and the only suggestion that
brought a consensus was to print all the supported MI versions, not
just one.  Let's not reopen that discussion again, even if the result
looks ``too much and misleading''.  (Why ``misleading'', btw?)

> although strictly speaking it should probably be:
> 
> 	mi-version="mi2"

Yes, mi-version is better, IMO.

Re: MI handshaking

[Bob Rossi]

On Sat, Nov 13, 2004 at 10:57:33AM +0200, Eli Zaretskii wrote:
> > Date: Fri, 12 Nov 2004 17:57:30 -0500
> > From: Andrew Cagney <cagney@gnu.org>
> > Cc: Bob Rossi <bob@brasko.net>, Nick Roberts <nick@nick.uklinux.net>,
> >         gdb-patches@sources.redhat.com
> > 
> > > =mi-handshake,versions=[mi1,mi2,mi3],stable=[mi2]
> > 
> > Yes, thanks for the correction with ``=''.   But not 
> > ``versions=[mi1,mi2,mi3]'' that's too much and misleading information.
> > 
> > I think the objective here needs to be to provide as much information as 
> > possible about what version of GDB and MI is running.  Hence the:
> > 
> > 	version="mi2"
> > 
> > (where hopefully VERSION version is a member of STABLE :-)
> 
> We've been through this discussion, and the only suggestion that
> brought a consensus was to print all the supported MI versions, not
> just one.  Let's not reopen that discussion again, even if the result
> looks ``too much and misleading''.  (Why ``misleading'', btw?)

Yeah, anyways it doesn't really matter for now. GDB only supports one
version, and I have a feeling it will stay that way for a long time.

Bob Rossi

Re: MI handshaking

[Alain Magloire]

> 
> On Sat, Nov 13, 2004 at 10:57:33AM +0200, Eli Zaretskii wrote:
> > > Date: Fri, 12 Nov 2004 17:57:30 -0500
> > > From: Andrew Cagney <cagney@gnu.org>
> > > Cc: Bob Rossi <bob@brasko.net>, Nick Roberts <nick@nick.uklinux.net>,
> > >         gdb-patches@sources.redhat.com
> > > 
> > > > =mi-handshake,versions=[mi1,mi2,mi3],stable=[mi2]
> > > 
> > > Yes, thanks for the correction with ``=''.   But not 
> > > ``versions=[mi1,mi2,mi3]'' that's too much and misleading information.
> > > 
> > > I think the objective here needs to be to provide as much information as 
> > > possible about what version of GDB and MI is running.  Hence the:
> > > 
> > > 	version="mi2"
> > > 
> > > (where hopefully VERSION version is a member of STABLE :-)
> > 
> > We've been through this discussion, and the only suggestion that
> > brought a consensus was to print all the supported MI versions, not
> > just one.  Let's not reopen that discussion again, even if the result
> > looks ``too much and misleading''.  (Why ``misleading'', btw?)
> 
> Yeah, anyways it doesn't really matter for now. GDB only supports one
> version, and I have a feeling it will stay that way for a long time.
> 

sigh ... sorry for being dense (hopefully this will not be a long thread)
but why are you keep on saying: "GDB only supports one version"
for example, I have gdb-6.1.x and I can start
# gdb -i mi1
# gdb -i mi2
# gdb -i mi3

that it is more then one version?

Re: MI handshaking

[Bob Rossi]

On Wed, Nov 17, 2004 at 10:17:57AM -0500, Alain Magloire wrote:
> > 
> > On Sat, Nov 13, 2004 at 10:57:33AM +0200, Eli Zaretskii wrote:
> > > > Date: Fri, 12 Nov 2004 17:57:30 -0500
> > > > From: Andrew Cagney <cagney@gnu.org>
> > > > Cc: Bob Rossi <bob@brasko.net>, Nick Roberts <nick@nick.uklinux.net>,
> > > >         gdb-patches@sources.redhat.com
> > > > 
> > > > > =mi-handshake,versions=[mi1,mi2,mi3],stable=[mi2]
> > > > 
> > > > Yes, thanks for the correction with ``=''.   But not 
> > > > ``versions=[mi1,mi2,mi3]'' that's too much and misleading information.
> > > > 
> > > > I think the objective here needs to be to provide as much information as 
> > > > possible about what version of GDB and MI is running.  Hence the:
> > > > 
> > > > 	version="mi2"
> > > > 
> > > > (where hopefully VERSION version is a member of STABLE :-)
> > > 
> > > We've been through this discussion, and the only suggestion that
> > > brought a consensus was to print all the supported MI versions, not
> > > just one.  Let's not reopen that discussion again, even if the result
> > > looks ``too much and misleading''.  (Why ``misleading'', btw?)
> > 
> > Yeah, anyways it doesn't really matter for now. GDB only supports one
> > version, and I have a feeling it will stay that way for a long time.
> > 
> 
> sigh ... sorry for being dense (hopefully this will not be a long thread)
> but why are you keep on saying: "GDB only supports one version"
> for example, I have gdb-6.1.x and I can start
> # gdb -i mi1
> # gdb -i mi2
> # gdb -i mi3
> 
> that it is more then one version?

oops, sorry, I meant to say that GDB supports only 1 stable MI version.
This is only relavent when discussing what GDB should do when the user
starts with 'gdb -i=mi'.

I see 2 needs stemming from this patch.
   
   - I need the handshaking to happen before any other I/O.
     This allows my front end to determine the protocol that is going to
     be used by GDB.

   - Alain, it seems like you need this command to be available after
     the fact. Even though this seems unintuitive to me, I understand
     that it's not a perfect world, and this info could be useful later
     on, especially if you are not responsible for staring GDB.

It seems as if there is two parts to this patch. The first part does the
handshaking, and that takes care of the protocol that should be used.
Here, GDB will give all of the info necessary to help the front end determine
the protocol that it wants to use. For instance, the protocols possible,
the build date, the GDB version, ...

Also, as a second part, a new MI command could be added, that simply
repeats all of the info determined from the handshaking functionality.
This would allow front ends to query the information later on, if for
some reason it couldn't do it originally. Note however, this would not
repeat the handshaking, and the version of MI being used can not be
changed. 

Would this be OK for everyone?

Thanks,
Bob Rossi

Re: MI handshaking

[Alain Magloire]

> 
> On Wed, Nov 17, 2004 at 10:17:57AM -0500, Alain Magloire wrote:
> > > 
> > > On Sat, Nov 13, 2004 at 10:57:33AM +0200, Eli Zaretskii wrote:
> > > > > Date: Fri, 12 Nov 2004 17:57:30 -0500
> > > > > From: Andrew Cagney <cagney@gnu.org>
> > > > > Cc: Bob Rossi <bob@brasko.net>, Nick Roberts <nick@nick.uklinux.net>,
> > > > >         gdb-patches@sources.redhat.com
> > > > > 
> > > > > > =mi-handshake,versions=[mi1,mi2,mi3],stable=[mi2]
> > > > > 
> > > > > Yes, thanks for the correction with ``=''.   But not 
> > > > > ``versions=[mi1,mi2,mi3]'' that's too much and misleading information.
> > > > > 
> > > > > I think the objective here needs to be to provide as much information as 
> > > > > possible about what version of GDB and MI is running.  Hence the:
> > > > > 
> > > > > 	version="mi2"
> > > > > 
> > > > > (where hopefully VERSION version is a member of STABLE :-)
> > > > 
> > > > We've been through this discussion, and the only suggestion that
> > > > brought a consensus was to print all the supported MI versions, not
> > > > just one.  Let's not reopen that discussion again, even if the result
> > > > looks ``too much and misleading''.  (Why ``misleading'', btw?)
> > > 
> > > Yeah, anyways it doesn't really matter for now. GDB only supports one
> > > version, and I have a feeling it will stay that way for a long time.
> > > 
> > 
> > sigh ... sorry for being dense (hopefully this will not be a long thread)
> > but why are you keep on saying: "GDB only supports one version"
> > for example, I have gdb-6.1.x and I can start
> > # gdb -i mi1
> > # gdb -i mi2
> > # gdb -i mi3
> > 
> > that it is more then one version?
> 
> oops, sorry, I meant to say that GDB supports only 1 stable MI version.
> This is only relavent when discussing what GDB should do when the user
> starts with 'gdb -i=mi'.
> 
> I see 2 needs stemming from this patch.
>    
>    - I need the handshaking to happen before any other I/O.
>      This allows my front end to determine the protocol that is going to
>      be used by GDB.
> 
>    - Alain, it seems like you need this command to be available after
>      the fact. Even though this seems unintuitive to me, I understand
>      that it's not a perfect world, and this info could be useful later
>      on, especially if you are not responsible for staring GDB.
> 

Yes.
Very true, it is not a perfect world but I also think it is rather inconsistent
that important information is lost once the screen scrolled away,
i.e. no way to retrieve it, beside restarting ...

> It seems as if there is two parts to this patch. The first part does the
> handshaking, and that takes care of the protocol that should be used.
> Here, GDB will give all of the info necessary to help the front end determine
> the protocol that it wants to use. For instance, the protocols possible,
> the build date, the GDB version, ...
> 
> Also, as a second part, a new MI command could be added, that simply
> repeats all of the info determined from the handshaking functionality.
> This would allow front ends to query the information later on, if for
> some reason it couldn't do it originally. Note however, this would not
> repeat the handshaking, and the version of MI being used can not be
> changed. 
> 

Yes.
I did not advocate to be able to change MI versions at runtime.
That would be overkill, i.e. it would be simpler to restart gdb
then to try to code that complexity with little benifits, IMHO

> Would this be OK for everyone?
> 

That would be good, and the proposed format suits me fine
mi-version="mi2",...

Thanks Bob for looking at this.

Re: MI handshaking

[Bob Rossi]

On Wed, Nov 17, 2004 at 08:35:32PM -0500, Alain Magloire wrote:
> > 
> > On Wed, Nov 17, 2004 at 10:17:57AM -0500, Alain Magloire wrote:
> > > > 
> > > > On Sat, Nov 13, 2004 at 10:57:33AM +0200, Eli Zaretskii wrote:
> > > > > > Date: Fri, 12 Nov 2004 17:57:30 -0500
> > > > > > From: Andrew Cagney <cagney@gnu.org>
> > > > > > Cc: Bob Rossi <bob@brasko.net>, Nick Roberts <nick@nick.uklinux.net>,
> > > > > >         gdb-patches@sources.redhat.com
> > > > > > 
> > > > > > > =mi-handshake,versions=[mi1,mi2,mi3],stable=[mi2]
> > > > > > 
> > > > > > Yes, thanks for the correction with ``=''.   But not 
> > > > > > ``versions=[mi1,mi2,mi3]'' that's too much and misleading information.
> > > > > > 
> > > > > > I think the objective here needs to be to provide as much information as 
> > > > > > possible about what version of GDB and MI is running.  Hence the:
> > > > > > 
> > > > > > 	version="mi2"
> > > > > > 
> > > > > > (where hopefully VERSION version is a member of STABLE :-)
> > > > > 
> > > > > We've been through this discussion, and the only suggestion that
> > > > > brought a consensus was to print all the supported MI versions, not
> > > > > just one.  Let's not reopen that discussion again, even if the result
> > > > > looks ``too much and misleading''.  (Why ``misleading'', btw?)
> > > > 
> > > > Yeah, anyways it doesn't really matter for now. GDB only supports one
> > > > version, and I have a feeling it will stay that way for a long time.
> > > > 
> > > 
> > > sigh ... sorry for being dense (hopefully this will not be a long thread)
> > > but why are you keep on saying: "GDB only supports one version"
> > > for example, I have gdb-6.1.x and I can start
> > > # gdb -i mi1
> > > # gdb -i mi2
> > > # gdb -i mi3
> > > 
> > > that it is more then one version?
> > 
> > oops, sorry, I meant to say that GDB supports only 1 stable MI version.
> > This is only relavent when discussing what GDB should do when the user
> > starts with 'gdb -i=mi'.
> > 
> > I see 2 needs stemming from this patch.
> >    
> >    - I need the handshaking to happen before any other I/O.
> >      This allows my front end to determine the protocol that is going to
> >      be used by GDB.
> > 
> >    - Alain, it seems like you need this command to be available after
> >      the fact. Even though this seems unintuitive to me, I understand
> >      that it's not a perfect world, and this info could be useful later
> >      on, especially if you are not responsible for staring GDB.
> > 
> 
> Yes.
> Very true, it is not a perfect world but I also think it is rather inconsistent
> that important information is lost once the screen scrolled away,
> i.e. no way to retrieve it, beside restarting ...
> 
> > It seems as if there is two parts to this patch. The first part does the
> > handshaking, and that takes care of the protocol that should be used.
> > Here, GDB will give all of the info necessary to help the front end determine
> > the protocol that it wants to use. For instance, the protocols possible,
> > the build date, the GDB version, ...
> > 
> > Also, as a second part, a new MI command could be added, that simply
> > repeats all of the info determined from the handshaking functionality.
> > This would allow front ends to query the information later on, if for
> > some reason it couldn't do it originally. Note however, this would not
> > repeat the handshaking, and the version of MI being used can not be
> > changed. 
> > 
> 
> Yes.
> I did not advocate to be able to change MI versions at runtime.
> That would be overkill, i.e. it would be simpler to restart gdb
> then to try to code that complexity with little benifits, IMHO
> 
> > Would this be OK for everyone?
> > 
> 
> That would be good, and the proposed format suits me fine
> mi-version="mi2",...
> 
> Thanks Bob for looking at this.

I've been very busy, so sorry about the delay.

I'll look into what we discussed here and come up with something that
fits all the new needs. Does Jim care about any of this?

Thanks,
Bob Rossi
> 

Re: MI handshaking

[Bob Rossi]

On Fri, Nov 19, 2004 at 02:23:13PM -0500, Bob Rossi wrote:
> On Wed, Nov 17, 2004 at 08:35:32PM -0500, Alain Magloire wrote:
> > > 
> > > On Wed, Nov 17, 2004 at 10:17:57AM -0500, Alain Magloire wrote:
> > > > > 
> > > > > On Sat, Nov 13, 2004 at 10:57:33AM +0200, Eli Zaretskii wrote:
> > > > > > > Date: Fri, 12 Nov 2004 17:57:30 -0500
> > > > > > > From: Andrew Cagney <cagney@gnu.org>
> > > > > > > Cc: Bob Rossi <bob@brasko.net>, Nick Roberts <nick@nick.uklinux.net>,
> > > > > > >         gdb-patches@sources.redhat.com
> > > > > > > 
> > > > > > > > =mi-handshake,versions=[mi1,mi2,mi3],stable=[mi2]
> > > > > > > 
> > > > > > > Yes, thanks for the correction with ``=''.   But not 
> > > > > > > ``versions=[mi1,mi2,mi3]'' that's too much and misleading information.
> > > > > > > 
> > > > > > > I think the objective here needs to be to provide as much information as 
> > > > > > > possible about what version of GDB and MI is running.  Hence the:
> > > > > > > 
> > > > > > > 	version="mi2"
> > > > > > > 
> > > > > > > (where hopefully VERSION version is a member of STABLE :-)
> > > > > > 
> > > > > > We've been through this discussion, and the only suggestion that
> > > > > > brought a consensus was to print all the supported MI versions, not
> > > > > > just one.  Let's not reopen that discussion again, even if the result
> > > > > > looks ``too much and misleading''.  (Why ``misleading'', btw?)
> > > > > 
> > > > > Yeah, anyways it doesn't really matter for now. GDB only supports one
> > > > > version, and I have a feeling it will stay that way for a long time.
> > > > > 
> > > > 
> > > > sigh ... sorry for being dense (hopefully this will not be a long thread)
> > > > but why are you keep on saying: "GDB only supports one version"
> > > > for example, I have gdb-6.1.x and I can start
> > > > # gdb -i mi1
> > > > # gdb -i mi2
> > > > # gdb -i mi3
> > > > 
> > > > that it is more then one version?
> > > 
> > > oops, sorry, I meant to say that GDB supports only 1 stable MI version.
> > > This is only relavent when discussing what GDB should do when the user
> > > starts with 'gdb -i=mi'.
> > > 
> > > I see 2 needs stemming from this patch.
> > >    
> > >    - I need the handshaking to happen before any other I/O.
> > >      This allows my front end to determine the protocol that is going to
> > >      be used by GDB.
> > > 
> > >    - Alain, it seems like you need this command to be available after
> > >      the fact. Even though this seems unintuitive to me, I understand
> > >      that it's not a perfect world, and this info could be useful later
> > >      on, especially if you are not responsible for staring GDB.
> > > 
> > 
> > Yes.
> > Very true, it is not a perfect world but I also think it is rather inconsistent
> > that important information is lost once the screen scrolled away,
> > i.e. no way to retrieve it, beside restarting ...
> > 
> > > It seems as if there is two parts to this patch. The first part does the
> > > handshaking, and that takes care of the protocol that should be used.
> > > Here, GDB will give all of the info necessary to help the front end determine
> > > the protocol that it wants to use. For instance, the protocols possible,
> > > the build date, the GDB version, ...
> > > 
> > > Also, as a second part, a new MI command could be added, that simply
> > > repeats all of the info determined from the handshaking functionality.
> > > This would allow front ends to query the information later on, if for
> > > some reason it couldn't do it originally. Note however, this would not
> > > repeat the handshaking, and the version of MI being used can not be
> > > changed. 
> > > 
> > 
> > Yes.
> > I did not advocate to be able to change MI versions at runtime.
> > That would be overkill, i.e. it would be simpler to restart gdb
> > then to try to code that complexity with little benifits, IMHO
> > 
> > > Would this be OK for everyone?
> > > 
> > 
> > That would be good, and the proposed format suits me fine
> > mi-version="mi2",...
> > 
> > Thanks Bob for looking at this.
> 
> I've been very busy, so sorry about the delay.
> 
> I'll look into what we discussed here and come up with something that
> fits all the new needs. Does Jim care about any of this?

Sorry about the delay.

I plan on getting at least this patch into GDB. So, to recap, I neede to add 
a new mi-command that would output all of the info discovered during the 
handshaking phase. Is there anything else that needs to be added?

Thanks,
Bob Rossi

Re: MI handshaking

[Jim Ingham]

On Jan 4, 2005, at 5:36 PM, Bob Rossi wrote:

>>
>> I've been very busy, so sorry about the delay.
>>
>> I'll look into what we discussed here and come up with something that
>> fits all the new needs. Does Jim care about any of this?

I didn't see this question in the original note.  The answer is we 
always ship the Developer Tools as a whole package, which includes 
Xcode & gdb, and just ask for the mi version we know it supports 
explicitly.  We don't support taking one version of gdb & using it 
under an older or newer version of Xcode.  I don't see any plans for us 
to separate the two in the forseeable future.  So while I do care about 
this in an abstract sort of way, I can't see us using it.


>
> Sorry about the delay.
>
> I plan on getting at least this patch into GDB. So, to recap, I neede 
> to add
> a new mi-command that would output all of the info discovered during 
> the
> handshaking phase. Is there anything else that needs to be added?
>

Xcode does use the "does this command exist" mi command Jason mentioned 
in a few places.  This was more for the convenience of the Xcode 
developers - so they could ask me to implement a command, then sketch 
out the implementation right away without having to wait for me to 
implement it.  That is the level of handshaking that we do.

Jim

Re: MI handshaking

[Bob Rossi]

On Tue, Jan 04, 2005 at 05:50:41PM -0800, Jim Ingham wrote:
> 
> On Jan 4, 2005, at 5:36 PM, Bob Rossi wrote:
> 
> >>
> >>I've been very busy, so sorry about the delay.
> >>
> >>I'll look into what we discussed here and come up with something that
> >>fits all the new needs. Does Jim care about any of this?
> 
> I didn't see this question in the original note.  The answer is we 
> always ship the Developer Tools as a whole package, which includes 
> Xcode & gdb, and just ask for the mi version we know it supports 
> explicitly.  We don't support taking one version of gdb & using it 
> under an older or newer version of Xcode.  I don't see any plans for us 
> to separate the two in the forseeable future.  So while I do care about 
> this in an abstract sort of way, I can't see us using it.
> 
> 
> >
> >Sorry about the delay.
> >
> >I plan on getting at least this patch into GDB. So, to recap, I neede 
> >to add
> >a new mi-command that would output all of the info discovered during 
> >the
> >handshaking phase. Is there anything else that needs to be added?
> >
> 
> Xcode does use the "does this command exist" mi command Jason mentioned 
> in a few places.  This was more for the convenience of the Xcode 
> developers - so they could ask me to implement a command, then sketch 
> out the implementation right away without having to wait for me to 
> implement it.  That is the level of handshaking that we do.

Thanks for the info, that sounds usefull. Is it available?

Thanks,
Bob Rossi

Re: MI handshaking

[Jim Ingham]

On Jan 4, 2005, at 5:53 PM, Bob Rossi wrote:

> On Tue, Jan 04, 2005 at 05:50:41PM -0800, Jim Ingham wrote:
>>
>> On Jan 4, 2005, at 5:36 PM, Bob Rossi wrote:
>>
>>>>
>>>> I've been very busy, so sorry about the delay.
>>>>
>>>> I'll look into what we discussed here and come up with something 
>>>> that
>>>> fits all the new needs. Does Jim care about any of this?
>>
>> I didn't see this question in the original note.  The answer is we
>> always ship the Developer Tools as a whole package, which includes
>> Xcode & gdb, and just ask for the mi version we know it supports
>> explicitly.  We don't support taking one version of gdb & using it
>> under an older or newer version of Xcode.  I don't see any plans for 
>> us
>> to separate the two in the forseeable future.  So while I do care 
>> about
>> this in an abstract sort of way, I can't see us using it.
>>
>>
>>>
>>> Sorry about the delay.
>>>
>>> I plan on getting at least this patch into GDB. So, to recap, I neede
>>> to add
>>> a new mi-command that would output all of the info discovered during
>>> the
>>> handshaking phase. Is there anything else that needs to be added?
>>>
>>
>> Xcode does use the "does this command exist" mi command Jason 
>> mentioned
>> in a few places.  This was more for the convenience of the Xcode
>> developers - so they could ask me to implement a command, then sketch
>> out the implementation right away without having to wait for me to
>> implement it.  That is the level of handshaking that we do.
>
> Thanks for the info, that sounds usefull. Is it available?

It's in the Darwin repository - you can get this by CVS or in tarball 
form or on the web.

http://developer.apple.com/darwin/projects/darwin/

is a good place to start.

It's a trivial command (we call it mi-verify-command):

enum mi_cmd_result
mi_cmd_mi_verify_command (char *command, char **argv, int argc)
{
   char 		*command_name = argv[0];
   struct mi_cmd *cmd;

   if (argc != 1)
     {
       error ("mi_cmd_mi_verify_command: Usage: MI_COMMAND_NAME.");
     }

   cmd = mi_lookup (command_name);

   ui_out_field_string (uiout, "name", command_name);
   if (cmd != NULL)
     {
        ui_out_field_string (uiout, "defined", "true");
        ui_out_field_string (uiout, "implemented",
             ((cmd->cli != NULL) ||
              (cmd->argv_func != NULL) ||
              (cmd->args_func != NULL)) ? "true" : "false");
     }
   else
     {
        ui_out_field_string (uiout, "defined", "false");
     }

   return MI_CMD_DONE;
}

Jim

>
> Thanks,
> Bob Rossi

Re: MI handshaking

[Bob Rossi]

Here is a patch for the MI handshaking code. In case you forgot, here is
how it acts from the client's perspective,
   $ ./gdb -i=mi
   handshake={stable_protocols={mi2}}
   ~"GNU gdb 6.3.50.20050105-cvs\n"
   ~"Copyright 2004 Free Software Foundation, Inc.\n"
   ~"GDB is free software, covered by the GNU General Public License, and you are\n"
   ~"welcome to change it and/or distribute copies of it under certain conditions.\n"
   ~"Type \"show copying\" to see the conditions.\n"
   ~"There is absolutely no warranty for GDB.  Type \"show warranty\" for details.\n"
   ~"This GDB was configured as \"i686-pc-linux-gnu\"."
   ~"\n"
   ~"Setting up the environment for debugging gdb.\n"
   &"No symbol table is loaded.  Use the \"file\" command.\n"
   &"No symbol table is loaded.  Use the \"file\" command.\n"
   &".gdbinit:8: Error in sourced command file:\n"
   &"No breakpoint number 0.\n"
   (gdb) 
   -handshake-info
   ^done,stable_protocol="2"
   (gdb) 
   
There are several things to note from this patch,

   1. The new 'handshake-info' command. It is intended to give all the
   information that the user selected during the handshaking phase of
   the MI protocol. So far the only thing worth showing is the protocol
   version that was selected

   2. If the GDB being queried was tested with and supports multiple
   protocols of MI, then GDB will block waiting for a response.

   3. The handshaking protocol is not in the typical MI syntax. Is this
   OK?

Finally, the testsuite will have to change before this commit is OK. Any
pointers on how to add the 'handshake={stable_protocols={mi2}}' to every
testcase?

Thanks,
Bob Rossi

Re: MI handshaking

[Bob Rossi]

On Tue, Jan 04, 2005 at 09:34:23PM -0500, Bob Rossi wrote:
> Here is a patch for the MI handshaking code. In case you forgot, here is
> how it acts from the client's perspective,
>    $ ./gdb -i=mi
>    handshake={stable_protocols={mi2}}
>    ~"GNU gdb 6.3.50.20050105-cvs\n"
>    ~"Copyright 2004 Free Software Foundation, Inc.\n"
>    ~"GDB is free software, covered by the GNU General Public License, and you are\n"
>    ~"welcome to change it and/or distribute copies of it under certain conditions.\n"
>    ~"Type \"show copying\" to see the conditions.\n"
>    ~"There is absolutely no warranty for GDB.  Type \"show warranty\" for details.\n"
>    ~"This GDB was configured as \"i686-pc-linux-gnu\"."
>    ~"\n"
>    ~"Setting up the environment for debugging gdb.\n"
>    &"No symbol table is loaded.  Use the \"file\" command.\n"
>    &"No symbol table is loaded.  Use the \"file\" command.\n"
>    &".gdbinit:8: Error in sourced command file:\n"
>    &"No breakpoint number 0.\n"
>    (gdb) 
>    -handshake-info
>    ^done,stable_protocol="2"
>    (gdb) 
>    
> There are several things to note from this patch,
> 
>    1. The new 'handshake-info' command. It is intended to give all the
>    information that the user selected during the handshaking phase of
>    the MI protocol. So far the only thing worth showing is the protocol
>    version that was selected
> 
>    2. If the GDB being queried was tested with and supports multiple
>    protocols of MI, then GDB will block waiting for a response.
> 
>    3. The handshaking protocol is not in the typical MI syntax. Is this
>    OK?
> 
> Finally, the testsuite will have to change before this commit is OK. Any
> pointers on how to add the 'handshake={stable_protocols={mi2}}' to every
> testcase?

I'm rusty, here's the patch I forgot to add. Also, the contents of the
new file I added (mi-cmd-handshake).

Is there a better place to add the new command? Currently I'm adding a
new file.

2005-01-04  Bob Rossi  <bob@brasko.net>

    * interps.c (struct interp): add field, handshake
    (interp_new): Add parameter, handshake
    (interp_can_handshake,interp_handshake): add function definitions
    * interps.h (interp_handshake_ftype): add typedef
    (interp_new): Add parameter, handshake
    (interp_can_handshake,interp_handshake): add function prototype
    * main.c (captured_main): Add the handshaking code
    * cli/cli-interp.c (_initialize_cli_interp): changed interface to
    interp_new
    * mi/mi-interp.c (stable_mi_versions): add table of stable MI versions
    (mi_handshake): Add function to do handshaking
    (_initialize_mi_interp): changed interface to interp_new
    * tui/tui-interp.c (_initialize_tui_interp): changed interface to
    interp_new
    * Makefile.in (SUBDIR_MI_OBJS,SUBDIR_MI_SRCS): added file mi-cmd-handshake
    (gdb/mi/ dependencies): same as above
    * mi/mi-cmd-file.c (mi_cmd_file_list_exec_source_file): removed unused
    variables in function.
    * mi/mi-cmds.c (mi_cmds): Add command handshake-info
    * mi/mi-cmds.h (mi_cmd-handshake-info): Add extern for new command above
    * mi/mi-cmd-handshake.c: Add new file for new handshake-info command.

mi/mi-cmd-handshake.c
/* MI Command Set - breakpoint and watchpoint commands.
   Copyright 2000, 2001, 2002 Free Software Foundation, Inc.
   Contributed by Cygnus Solutions (a Red Hat company).

   This file is part of GDB.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place - Suite 330,
   Boston, MA 02111-1307, USA.  */

#include "defs.h"
#include "mi-cmds.h"
#include "mi-getopt.h"
#include "ui-out.h"
#include "mi-out.h"

enum mi_cmd_result
mi_cmd_handshake_info(char *command, char **argv, int argc)
{
  if ( !mi_valid_noargs("mi_cmd_file_list_exec_source_file", argc, argv) )
    error ("mi_cmd_file_list_exec_source_file: Usage: No args");

  ui_out_field_int (uiout, "stable_protocol", mi_version(uiout));

  return MI_CMD_DONE;
}

Index: Makefile.in
===================================================================
RCS file: /cvs/src/src/gdb/Makefile.in,v
retrieving revision 1.681
diff -w -u -r1.681 Makefile.in
--- Makefile.in	4 Jan 2005 22:59:44 -0000	1.681
+++ Makefile.in	5 Jan 2005 02:35:16 -0000
@@ -169,14 +169,14 @@
 SUBDIR_MI_OBS = \
 	mi-out.o mi-console.o \
 	mi-cmds.o mi-cmd-env.o mi-cmd-var.o mi-cmd-break.o mi-cmd-stack.o \
-	mi-cmd-file.o mi-cmd-disas.o mi-symbol-cmds.o \
+	mi-cmd-file.o mi-cmd-handshake.o mi-cmd-disas.o mi-symbol-cmds.o \
 	mi-interp.o \
 	mi-main.o mi-parse.o mi-getopt.o
 SUBDIR_MI_SRCS = \
 	mi/mi-out.c mi/mi-console.c \
 	mi/mi-cmds.c mi/mi-cmd-env.c \
 	mi/mi-cmd-var.c mi/mi-cmd-break.c mi/mi-cmd-stack.c \
-	mi/mi-cmd-file.c mi/mi-cmd-disas.c mi/mi-symbol-cmds.c \
+	mi/mi-cmd-file.c mi/mi-cmd-handshake.c mi/mi-cmd-disas.c mi/mi-symbol-cmds.c \
 	mi/mi-interp.c \
 	mi/mi-main.c mi/mi-parse.c mi/mi-getopt.c
 SUBDIR_MI_DEPS =
@@ -2915,6 +2915,9 @@
 mi-cmd-file.o: $(srcdir)/mi/mi-cmd-file.c $(defs_h) $(mi_cmds_h) \
 	$(mi_getopt_h) $(ui_out_h) $(symtab_h) $(source_h) $(objfiles_h)
 	$(CC) -c $(INTERNAL_CFLAGS) $(srcdir)/mi/mi-cmd-file.c
+mi-cmd-handshake.o: $(srcdir)/mi/mi-cmd-handshake.c $(defs_h) $(mi_cmds_h) \
+	$(mi_getopt_h) $(ui_out_h) $(mi_out_h)
+	$(CC) -c $(INTERNAL_CFLAGS) $(srcdir)/mi/mi-cmd-handshake.c
 mi-cmds.o: $(srcdir)/mi/mi-cmds.c $(defs_h) $(top_h) $(mi_cmds_h) \
 	$(gdb_string_h)
 	$(CC) -c $(INTERNAL_CFLAGS) $(srcdir)/mi/mi-cmds.c
Index: interps.c
===================================================================
RCS file: /cvs/src/src/gdb/interps.c,v
retrieving revision 1.8
diff -w -u -r1.8 interps.c
--- interps.c	13 Sep 2004 18:26:30 -0000	1.8
+++ interps.c	5 Jan 2005 02:35:17 -0000
@@ -68,6 +68,8 @@
 
   const struct interp_procs *procs;
   int quiet_p;
+
+  interp_handshake_ftype *handshake;
 };
 
 /* Functions local to this file. */
@@ -90,7 +92,7 @@
    interpreter. */
 struct interp *
 interp_new (const char *name, void *data, struct ui_out *uiout,
-	    const struct interp_procs *procs)
+	    const struct interp_procs *procs, interp_handshake_ftype *handshake)
 {
   struct interp *new_interp;
 
@@ -102,6 +104,7 @@
   new_interp->quiet_p = 0;
   new_interp->procs = procs;
   new_interp->inited = 0;
+  new_interp->handshake = handshake;
 
   return new_interp;
 }
@@ -239,6 +242,22 @@
   return current_interpreter->interpreter_out;
 }
 
+int
+interp_can_handshake (struct interp *interp)
+{
+  if (interp != NULL)
+    if (interp->handshake)
+      return 1;
+
+  return 0;
+}
+
+struct interp *
+interp_handshake (struct interp *interp) 
+{
+    return interp_lookup (interp->handshake (gdb_stdout, gdb_stdin));
+}
+
 /* Returns true if the current interp is the passed in name. */
 int
 current_interp_named_p (const char *interp_name)
Index: interps.h
===================================================================
RCS file: /cvs/src/src/gdb/interps.h,v
retrieving revision 1.6
diff -w -u -r1.6 interps.h
--- interps.h	18 Feb 2004 19:01:36 -0000	1.6
+++ interps.h	5 Jan 2005 02:35:17 -0000
@@ -40,6 +40,7 @@
 typedef int (interp_prompt_p_ftype) (void *data);
 typedef int (interp_exec_ftype) (void *data, const char *command);
 typedef void (interp_command_loop_ftype) (void *data);
+typedef const char *(interp_handshake_ftype) (struct ui_file *gdb_stdout, struct ui_file *gdb_stdin);
 
 struct interp_procs
 {
@@ -53,11 +54,14 @@
 
 extern struct interp *interp_new (const char *name, void *data,
 				  struct ui_out *uiout,
-				  const struct interp_procs *procs);
+		const struct interp_procs *procs,
+		interp_handshake_ftype *handshake);
 extern void interp_add (struct interp *interp);
 extern int interp_set (struct interp *interp);
 extern struct interp *interp_lookup (const char *name);
 extern struct ui_out *interp_ui_out (struct interp *interp);
+extern int interp_can_handshake (struct interp *interp);
+extern struct interp *interp_handshake (struct interp *interp);
 
 extern int current_interp_named_p (const char *name);
 extern int current_interp_display_prompt_p (void);
Index: main.c
===================================================================
RCS file: /cvs/src/src/gdb/main.c,v
retrieving revision 1.45
diff -w -u -r1.45 main.c
--- main.c	7 Dec 2004 11:06:03 -0000	1.45
+++ main.c	5 Jan 2005 02:35:18 -0000
@@ -562,8 +562,13 @@
   {
     /* Find it.  */
     struct interp *interp = interp_lookup (interpreter_p);
+
+    if (interp && interp_can_handshake (interp))
+		interp = interp_handshake (interp);
+
     if (interp == NULL)
       error ("Interpreter `%s' unrecognized", interpreter_p);
+
     /* Install it.  */
     if (!interp_set (interp))
       {
Index: cli/cli-interp.c
===================================================================
RCS file: /cvs/src/src/gdb/cli/cli-interp.c,v
retrieving revision 1.4
diff -w -u -r1.4 cli-interp.c
--- cli/cli-interp.c	3 Jul 2003 14:49:26 -0000	1.4
+++ cli/cli-interp.c	5 Jan 2005 02:35:18 -0000
@@ -151,7 +151,7 @@
 
   /* Create a default uiout builder for the CLI. */
   cli_uiout = cli_out_new (gdb_stdout);
-  cli_interp = interp_new (INTERP_CONSOLE, NULL, cli_uiout, &procs);
+  cli_interp = interp_new (INTERP_CONSOLE, NULL, cli_uiout, &procs, NULL);
 
   interp_add (cli_interp);
 }
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.229
diff -w -u -r1.229 gdb.texinfo
--- doc/gdb.texinfo	8 Dec 2004 05:28:31 -0000	1.229
+++ doc/gdb.texinfo	5 Jan 2005 02:35:30 -0000
@@ -15022,6 +15022,7 @@
 @menu
 * GDB/MI Command Syntax::
 * GDB/MI Compatibility with CLI::
+* GDB/MI Handshaking Interface::
 * GDB/MI Output Records::
 * GDB/MI Command Description Format::
 * GDB/MI Breakpoint Table Commands::
@@ -15046,11 +15047,53 @@
 @section @sc{gdb/mi} Command Syntax
 
 @menu
+* GDB/MI Handshaking Syntax::
 * GDB/MI Input Syntax::
 * GDB/MI Output Syntax::
 * GDB/MI Simple Examples::
 @end menu
 
+@node GDB/MI Handshaking Syntax
+@subsection @sc{gdb/mi} Handshaking Syntax
+
+@cindex handshaking syntax for @sc{gdb/mi}
+@cindex @sc{gdb/mi}, handshaking syntax
+@table @code
+@item @var{handshake_output} @expansion{}
+@code{"handshake=@{stable_protocols=@{" @var{mi-protocol-list} 
+"@}" @var{nl}}
+
+@item @var{mi-protocol-list} @expansion{}
+@code{ epsilon | @var{mi-protocol} | @var{mi-protocol-list} "," @var{mi-protocol} }
+
+@item @var{mi-protocol} @expansion{}
+@code{ "mi" @var{token} }
+
+@item @var{token} @expansion{}
+"any sequence of digits"
+
+@item @var{nl} @expansion{}
+@code{CR | CR-LF}
+@end table
+
+@noindent
+Notes:
+
+@itemize @bullet
+@item
+If only one stable @sc{mi} protocol is supported by a particular release of 
+@value{GDBN}, then that release is used and the caller does not have to
+do anything.
+
+@item
+If there is more than one stable @sc{mi} protocol supported by a particular 
+release of @value{GDBN}, then the caller has to specify which version of the
+@sc{mi} protocol it wants @value{GDBN} to communicate with.
+
+@end itemize
+
+For more information on handshaking see @ref{GDB/MI Handshaking Interface}.
+
 @node GDB/MI Input Syntax
 @subsection @sc{gdb/mi} Input Syntax
 
@@ -15339,6 +15382,51 @@
 an un-supported hybrid of @sc{gdb/mi} and CLI output.
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Handshaking Interface
+@section @sc{gdb/mi} Handshaking Interface
+
+@cindex @sc{gdb/mi}, handshaking interface
+@value{GDBN} is capable of speaking several MI protocols at a time.  This
+interface is intended to help developers understand what version of the MI
+protocol that a particular @value{GDBN} is going to communicate with.
+
+It is possible to start the @sc{gdb/mi} interpreter using @samp{-i=mi@var{n}}, 
+where @var{n} is the MI protocol version (@pxref{Interpreters}).  When invoked 
+with a specific version of the MI interpreter, @value{GDBN} will bypass the 
+handshaking mode and go directly into the version of the MI that it requested.  
+However, if @value{GDBN} is started with the @samp{-i=mi} flag, then this tells 
+@value{GDBN} to go into its handshaking mode with the client to determine the 
+correct MI protocol to communicate with.
+
+@value{GDBN} will output all of the stable versions of the MI protocol that
+it supports.  The term @dfn{stable MI protocol} simply means that the protocol
+was tested when this particular release was made.  Protocols that are no longer
+tested in the @value{GDBN} testsuite will not be considered a stable release.  
+If the caller still wishes to communicate with @value{GDBN} using one of these
+untested protocols, they could simply try to invoke @value{GDBN} with 
+@samp{-i=mi@var{n}}, where @var{n} is version they wish to communicate with.
+
+@value{GDBN} will output all of the stable MI versions that it supports.  
+If a specific version of @value{GDBN} speaks only one stable MI protocol then
+it will begin communicating with that version of the protocol.  The front end
+has no way to change this version.  However, if @value{GDBN} speaks several 
+versions of the MI protocol, then it will output a list of these protocols 
+and the front end then has to choose the version that it wants @value{GDBN}
+to communicate with.
+
+@cindex stable MI protocol
+You could have a @value{GDBN} version that is capable of communicating with
+several versions of the @sc{mi} protocol.  In general, an official release or
+a CVS snapshot will have deprecated @sc{mi} protocols, stable @sc{mi} 
+protocols and development @sc{mi} protocols.  The deprecated @sc{mi} protocols
+are kept around in @value{GDBN} for some period of time and then will 
+eventually get removed.  The stable MI protocols are considered stable
+because they were tested when the particular @value{GDBN} program you have was
+created.  The development @sc{mi} protocols are not ready to be used since
+there is a good change there will be incompatible changes made to it before it
+can become a stable protocol.
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Output Records
 @section @sc{gdb/mi} Output Records
 
Index: mi/mi-cmd-file.c
===================================================================
RCS file: /cvs/src/src/gdb/mi/mi-cmd-file.c,v
retrieving revision 1.2
diff -w -u -r1.2 mi-cmd-file.c
--- mi/mi-cmd-file.c	10 Jun 2004 20:05:45 -0000	1.2
+++ mi/mi-cmd-file.c	5 Jan 2005 02:35:30 -0000
@@ -34,8 +34,6 @@
 mi_cmd_file_list_exec_source_file(char *command, char **argv, int argc)
 {
   struct symtab_and_line st;
-  int optind = 0;
-  char *optarg;
   
   if ( !mi_valid_noargs("mi_cmd_file_list_exec_source_file", argc, argv) )
     error ("mi_cmd_file_list_exec_source_file: Usage: No args");
Index: mi/mi-cmds.c
===================================================================
RCS file: /cvs/src/src/gdb/mi/mi-cmds.c,v
retrieving revision 1.15
diff -w -u -r1.15 mi-cmds.c
--- mi/mi-cmds.c	10 Jun 2004 20:05:45 -0000	1.15
+++ mi/mi-cmds.c	5 Jan 2005 02:35:30 -0000
@@ -91,6 +91,7 @@
   { "gdb-show", { "show", 1 }, NULL, NULL },
   { "gdb-source", { NULL, 0 }, NULL, NULL },
   { "gdb-version", { "show version", 0 }, 0 },
+  { "handshake-info", { NULL, 0 }, 0, mi_cmd_handshake_info},
   { "interpreter-exec", { NULL, 0 }, 0, mi_cmd_interpreter_exec},
   { "kod-info", { NULL, 0 }, NULL, NULL },
   { "kod-list", { NULL, 0 }, NULL, NULL },
Index: mi/mi-cmds.h
===================================================================
RCS file: /cvs/src/src/gdb/mi/mi-cmds.h,v
retrieving revision 1.14
diff -w -u -r1.14 mi-cmds.h
--- mi/mi-cmds.h	10 Jun 2004 20:05:45 -0000	1.14
+++ mi/mi-cmds.h	5 Jan 2005 02:35:30 -0000
@@ -89,6 +89,7 @@
 extern mi_cmd_argv_ftype mi_cmd_file_list_exec_source_file;
 extern mi_cmd_argv_ftype mi_cmd_file_list_exec_source_files;
 extern mi_cmd_argv_ftype mi_cmd_gdb_exit;
+extern mi_cmd_argv_ftype mi_cmd_handshake_info;
 extern mi_cmd_argv_ftype mi_cmd_interpreter_exec;
 extern mi_cmd_argv_ftype mi_cmd_stack_info_depth;
 extern mi_cmd_argv_ftype mi_cmd_stack_list_args;
Index: mi/mi-interp.c
===================================================================
RCS file: /cvs/src/src/gdb/mi/mi-interp.c,v
retrieving revision 1.11
diff -w -u -r1.11 mi-interp.c
--- mi/mi-interp.c	13 Sep 2004 18:26:31 -0000	1.11
+++ mi/mi-interp.c	5 Jan 2005 02:35:30 -0000
@@ -364,6 +364,66 @@
   start_event_loop ();
 }
 
+/* The latest stable mi version that is being tested.
+   There could potentially be several versions of MI that are stable
+   at a time. */
+static const int stable_mi_versions[] = 
+{
+  2,
+  0
+};
+
+/* Allows MI and the front end to agree on an MI protocol.
+   
+   All of the stable MI versions are currently printed. If there is more
+   than one stable MI version, than it is expected the user will write
+   back the version they want to communicate with. 
+   
+   Returns the MI version string the user requested, or if there is only
+   one version, that string is returned. */
+static const char *mi_handshake (struct ui_file *gdb_stdout,
+	struct ui_file *gdb_stdin)
+{
+  static char mi_buf[32]; 
+  int i;
+
+  if (!gdb_stdout || !gdb_stdin)
+	  return NULL;
+
+  /* Output the header, can't use mi_out stuff because no mi has
+	 been chosen and initialized yet. */
+  fprintf_unfiltered ( gdb_stdout, "handshake={stable_protocols={" );
+
+  /* Output all the stable versions */
+  for (i = 0; stable_mi_versions[i] != 0; ++i ) 
+    {
+      if (i > 0)
+        fprintf_unfiltered (gdb_stdout, ",");
+
+        fprintf_unfiltered (gdb_stdout, "mi%d", stable_mi_versions[i] );
+    }
+
+  fprintf_unfiltered ( gdb_stdout, "}}\n" );
+	
+  /* If there was more than one stable version outputted, ask the front
+	 end which one it should use */
+  if ( i > 1 ) 
+  {
+    int size;
+	size = ui_file_read ( gdb_stdin, mi_buf, 31 );
+	mi_buf[size--] = 0; /* null terminate, and remove new line */
+	while ( size >= 0 && (mi_buf[size] == '\n' || mi_buf[size] == '\r') )
+      mi_buf[size--] = 0;
+
+	/* The mi option is not valid in this mode. */
+	if ( strcmp ( mi_buf, "mi" ) == 0 )
+      return NULL;
+  } else
+    sprintf ( mi_buf, "mi%d", stable_mi_versions[0] );
+
+  return mi_buf;
+}
+
 extern initialize_file_ftype _initialize_mi_interp; /* -Wmissing-prototypes */
 
 void
@@ -379,11 +439,11 @@
   };
 
   /* The various interpreter levels.  */
-  interp_add (interp_new (INTERP_MI1, NULL, mi_out_new (1), &procs));
-  interp_add (interp_new (INTERP_MI2, NULL, mi_out_new (2), &procs));
-  interp_add (interp_new (INTERP_MI3, NULL, mi_out_new (3), &procs));
+  interp_add (interp_new (INTERP_MI1, NULL, mi_out_new (1), &procs, NULL));
+  interp_add (interp_new (INTERP_MI2, NULL, mi_out_new (2), &procs, NULL));
+  interp_add (interp_new (INTERP_MI3, NULL, mi_out_new (3), &procs, NULL));
 
   /* "mi" selects the most recent released version.  "mi2" was
      released as part of GDB 6.0.  */
-  interp_add (interp_new (INTERP_MI, NULL, mi_out_new (2), &procs));
+  interp_add (interp_new (INTERP_MI, NULL, mi_out_new (stable_mi_versions[0]), &procs, mi_handshake));
 }
Index: tui/tui-interp.c
===================================================================
RCS file: /cvs/src/src/gdb/tui/tui-interp.c,v
retrieving revision 1.5
diff -w -u -r1.5 tui-interp.c
--- tui/tui-interp.c	7 Feb 2004 04:40:36 -0000	1.5
+++ tui/tui-interp.c	5 Jan 2005 02:35:31 -0000
@@ -198,7 +198,7 @@
 
   /* Create a default uiout builder for the TUI. */
   tui_out = tui_out_new (gdb_stdout);
-  interp_add (interp_new ("tui", NULL, tui_out, &procs));
+  interp_add (interp_new ("tui", NULL, tui_out, &procs, NULL));
   if (interpreter_p && strcmp (interpreter_p, "tui") == 0)
     tui_start_enabled = 1;
 

Re: MI handshaking

[Alain Magloire]

> 
> > Date: Fri, 12 Nov 2004 17:57:30 -0500
> > From: Andrew Cagney <cagney@gnu.org>
> > Cc: Bob Rossi <bob@brasko.net>, Nick Roberts <nick@nick.uklinux.net>,
> >         gdb-patches@sources.redhat.com
> > 
> > > =mi-handshake,versions=[mi1,mi2,mi3],stable=[mi2]
> > 
> > Yes, thanks for the correction with ``=''.   But not 
> > ``versions=[mi1,mi2,mi3]'' that's too much and misleading information.
> > 
> > I think the objective here needs to be to provide as much information as 
> > possible about what version of GDB and MI is running.  Hence the:
> > 
> > 	version="mi2"
> > 
> > (where hopefully VERSION version is a member of STABLE :-)
> 
> We've been through this discussion, and the only suggestion that
> brought a consensus was to print all the supported MI versions, not
> just one.  Let's not reopen that discussion again, even if the result
> looks ``too much and misleading''.  (Why ``misleading'', btw?)
> 
> > although strictly speaking it should probably be:
> > 
> > 	mi-version="mi2"
> 
> Yes, mi-version is better, IMO.
> 

Right 8-).

But it would also be nice to have a command that would show this 
information.  It will bring symmetry/consistency:
- If you want to see the information again, then the only
  would be to kill gdb and restart again ?

- Most of the information in the prologue blurb can be retrieve:
   show version
   show annotate
   show copying
   show warranty
  Why would the mi-version be different ?

- It would be a big advantage to a frontend  ... well at least to me 8-)
  In our case, we do not necessarly spawn gdb, the process is spawn
  by a delegate.  For now I can just rely on smart guesses:
   --interpreter-exec console "echo"  --> working good that means mi2 and above
  no fun and easy to get wrong.


-- 
au revoir, alain
----
Aussi haut que l'on soit assis, on est toujours assis que sur son cul !!!

Re: MI handshaking

[Eli Zaretskii]

> Date: Wed, 17 Nov 2004 10:14:12 -0500 (EST)
> From: "Alain Magloire" <alain@qnx.com>
> Cc: cagney@gnu.org (Andrew Cagney), alain@qnx.com, bob@brasko.net,
>         nick@nick.uklinux.net, gdb-patches@sources.redhat.com
> 
> But it would also be nice to have a command that would show this 
> information.

If this is a real need, then IMHO let's have such a command.
The MI interpreter could start by issuing that command internally,
thus outputting the info right after the copyright blurb.