This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[rfa/doc] Add version to XML target descriptions
- From: Daniel Jacobowitz <drow at false dot org>
- To: gdb-patches at sourceware dot org
- Date: Tue, 12 Jun 2007 08:37:31 -0400
- Subject: [rfa/doc] Add version to XML target descriptions
Carlos O'Donell suggested that our XML descriptions should have a
format version number in them, which may simplify future changes.
This patch adds a marker. The use of #FIXED means that omitting the
version is OK - GDB will assume it's the version that GDB knows about.
But if you include the version, and GDB changes to a new version, then
the version marker will cause GDB to give a sensible error (or allow a
hypothetical future GDB to handle multiple versions of the format).
Eli, does the documentation update look OK?
Once this patch is committed I will update the copy on the web site
too.
--
Daniel Jacobowitz
CodeSourcery
2007-06-12 Daniel Jacobowitz <dan@codesourcery.com>
* gdb.texinfo (Target Description Format): Add version attribute
for <target>.
* xml-tdesc.c (tdesc_start_target): New.
(target_attributes): New.
(tdesc_elements): Use it.
* features/gdb-target.dtd: Add #FIXED version attribute for
<target>.
Index: gdb/doc/gdb.texinfo
===================================================================
--- gdb/doc/gdb.texinfo (revision 173463)
+++ gdb/doc/gdb.texinfo (working copy)
@@ -25478,7 +25478,7 @@ target, or to warn you if you connect to
Here is a simple target description:
@smallexample
-<target>
+<target version="1.0">
<architecture>i386:x86-64</architecture>
</target>
@end smallexample
@@ -25494,7 +25494,7 @@ are explained further below.
@smallexample
<?xml version="1.0"?>
<!DOCTYPE target SYSTEM "gdb-target.dtd">
-<target>
+<target version="1.0">
@r{[}@var{architecture}@r{]}
@r{[}@var{feature}@dots{}@r{]}
</target>
@@ -25505,7 +25505,11 @@ The description is generally insensitive
breaks, under the usual common-sense rules. The XML version
declaration and document type declaration can generally be omitted
(@value{GDBN} does not require them), but specifying them may be
-useful for XML validation tools.
+useful for XML validation tools. The version attribute for
+@samp{<target>} may also be omitted, but we recommend
+including it; if future versions of @value{GDBN} use an incompatible
+revision of @file{gdb-target.dtd}, they will detect and report
+the version mismatch.
@subsection Inclusion
@cindex target descriptions, inclusion
Index: gdb/xml-tdesc.c
===================================================================
--- gdb/xml-tdesc.c (revision 173463)
+++ gdb/xml-tdesc.c (working copy)
@@ -126,6 +126,22 @@ tdesc_end_arch (struct gdb_xml_parser *p
set_tdesc_architecture (data->tdesc, arch);
}
+/* Handle the start of a <target> element. */
+
+static void
+tdesc_start_target (struct gdb_xml_parser *parser,
+ const struct gdb_xml_element *element,
+ void *user_data, VEC(gdb_xml_value_s) *attributes)
+{
+ struct tdesc_parsing_data *data = user_data;
+ char *version = VEC_index (gdb_xml_value_s, attributes, 0)->value;
+
+ if (strcmp (version, "1.0") != 0)
+ gdb_xml_error (parser,
+ _("Target description has unsupported version \"%s\""),
+ version);
+}
+
/* Handle the start of a <feature> element. */
static void
@@ -599,6 +615,11 @@ static const struct gdb_xml_element feat
{ NULL, NULL, NULL, GDB_XML_EF_NONE, NULL, NULL }
};
+static const struct gdb_xml_attribute target_attributes[] = {
+ { "version", GDB_XML_AF_NONE, NULL, NULL },
+ { NULL, GDB_XML_AF_NONE, NULL, NULL }
+};
+
static const struct gdb_xml_element target_children[] = {
{ "architecture", NULL, NULL, GDB_XML_EF_OPTIONAL,
NULL, tdesc_end_arch },
@@ -611,8 +632,8 @@ static const struct gdb_xml_element targ
};
static const struct gdb_xml_element tdesc_elements[] = {
- { "target", NULL, target_children, GDB_XML_EF_NONE,
- NULL, NULL },
+ { "target", target_attributes, target_children, GDB_XML_EF_NONE,
+ tdesc_start_target, NULL },
{ NULL, NULL, NULL, GDB_XML_EF_NONE, NULL, NULL }
};
Index: gdb/features/gdb-target.dtd
===================================================================
--- gdb/features/gdb-target.dtd (revision 173463)
+++ gdb/features/gdb-target.dtd (working copy)
@@ -7,6 +7,8 @@
<!-- The root element of a GDB target description is <target>. -->
<!ELEMENT target (architecture?, feature*)>
+<!ATTLIST target
+ version CDATA #FIXED "1.0">
<!ELEMENT architecture (#PCDATA)>