gdb/python: add gdb.RemoteTargetConnection.send_packet

This commits adds a new sub-class of gdb.TargetConnection,
gdb.RemoteTargetConnection.  This sub-class is created for all
'remote' and 'extended-remote' targets.

This new sub-class has one additional method over its base class,
'send_packet'.  This new method is equivalent to the 'maint
packet' CLI command, it allows a custom packet to be sent to a remote
target.

The outgoing packet can either be a bytes object, or a Unicode string,
so long as the Unicode string contains only ASCII characters.

The result of calling RemoteTargetConnection.send_packet is a bytes
object containing the reply that came from the remote.

4 files changed, 316 insertions, 4 deletions

diff --git a/gdb/testsuite/gdb.python/py-connection.exp b/gdb/testsuite/gdb.python/py-connection.exp
index b805b05..96c8378 100644
--- a/gdb/testsuite/gdb.python/py-connection.exp
+++ b/gdb/testsuite/gdb.python/py-connection.exp
@@ -33,12 +33,18 @@ if ![runto_main] then {
     return 0
 }
 
+if { [target_info exists gdb_protocol] } {
+    set connection_type "RemoteTargetConnection"
+} else {
+    set connection_type "TargetConnection"
+}
+
 # Create a gdb.TargetConnection object and check it is initially
 # valid.
 gdb_test_no_output "python conn = gdb.selected_inferior().connection"
 gdb_test "python print(conn)" \
-    "<gdb.TargetConnection num=1, what=\"\[^\"\]+\">" \
-    "print gdb.TargetConnection while it is still valid"
+    "<gdb.${connection_type} num=1, what=\"\[^\"\]+\">" \
+    "print gdb.${connection_type} while it is still valid"
 gdb_test "python print(conn.is_valid())" "True" "is_valid returns True"
 
 # Get the connection again, and ensure we get the exact same object.
@@ -53,8 +59,8 @@ gdb_test "disconnect" "" "kill the inferior" \
     "A program is being debugged already\\.  Kill it\\? .*y or n. $" "y"
 gdb_test "info connections" "No connections\\." \
     "info connections now all the connections have gone"
-gdb_test "python print(conn)" "<gdb.TargetConnection \\(invalid\\)>" \
-    "print gdb.TargetConnection now its invalid"
+gdb_test "python print(conn)" "<gdb.${connection_type} \\(invalid\\)>" \
+    "print gdb.${connection_type} now its invalid"
 gdb_test "python print(conn.is_valid())" "False" "is_valid returns False"
 
 # Now check that accessing properties of the invalid connection cases
diff --git a/gdb/testsuite/gdb.python/py-send-packet.c b/gdb/testsuite/gdb.python/py-send-packet.c
new file mode 100644
index 0000000..49fbd79
--- /dev/null
+++ b/gdb/testsuite/gdb.python/py-send-packet.c
@@ -0,0 +1,31 @@
+/* This testcase is part of GDB, the GNU debugger.
+
+   Copyright 2021 Free Software Foundation, Inc.
+
+   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 3 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, see <http://www.gnu.org/licenses/>.  */
+
+volatile int global_var = 0;
+
+void
+breakpt ()
+{
+  /* Nothing.  */
+}
+
+int
+main (void)
+{
+  breakpt ();
+  return 0;
+}
diff --git a/gdb/testsuite/gdb.python/py-send-packet.exp b/gdb/testsuite/gdb.python/py-send-packet.exp
new file mode 100644
index 0000000..5903575
--- /dev/null
+++ b/gdb/testsuite/gdb.python/py-send-packet.exp
@@ -0,0 +1,99 @@
+# Copyright (C) 2021 Free Software Foundation, Inc.
+
+# 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 3 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, see <http://www.gnu.org/licenses/>.
+
+# Test the gdb.RemoteTargetConnection.send_packet API.  This is done
+# by connecting to a remote target and fetching the thread list in two
+# ways, first, we manually send the packets required to read the
+# thread list using gdb.TargetConnection.send_packet, then we compare
+# the results to the thread list using the standard API calls.
+
+load_lib gdb-python.exp
+load_lib gdbserver-support.exp
+
+standard_testfile
+
+if {[skip_gdbserver_tests]} {
+    return 0
+}
+
+if { [prepare_for_testing "failed to prepare" ${testfile} ${srcfile}] } {
+    return -1
+}
+
+if { [skip_python_tests] } {
+    return 0
+}
+
+# Make sure we're disconnected, in case we're testing with an
+# extended-remote board, therefore already connected.
+gdb_test "disconnect" ".*"
+
+gdbserver_run ""
+
+gdb_breakpoint "breakpt"
+gdb_continue_to_breakpoint "breakpt"
+
+# Source the python script.
+set remote_python_file [gdb_remote_download host \
+			    ${srcdir}/${subdir}/${testfile}.py]
+gdb_test "source $remote_python_file" "Sourcing complete\\." \
+    "source ${testfile}.py script"
+
+# The test is actually written in the Python script.  Run it now.
+gdb_test "python run_send_packet_test()" "Send packet test passed"
+
+# Check the string representation of a remote target connection.
+gdb_test "python print(gdb.selected_inferior().connection)" \
+    "<gdb.RemoteTargetConnection num=$decimal, what=\".*\">"
+
+# Check to see if there's any auxv data for this target.
+gdb_test_multiple "info auxv" "" {
+    -re -wrap "The program has no auxiliary information now\\. " {
+	set skip_auxv_test true
+    }
+    -re -wrap "0\\s+AT_NULL\\s+End of vector\\s+0x0" {
+	set skip_auxv_test false
+    }
+}
+
+if { ! $skip_auxv_test } {
+    # Use 'maint packet' to fetch the auxv data.
+    set reply_data ""
+    gdb_test_multiple "maint packet qXfer:auxv:read::0,1000" "" {
+	-re "sending: \"qXfer:auxv:read::0,1000\"\r\n" {
+	    exp_continue
+	}
+	-re -wrap "received: \"(.*)\"" {
+	    set reply_data $expect_out(1,string)
+	}
+    }
+
+    # Expand the '\x' in the output, so we can pass a string through
+    # to Python.
+    set reply_data [string map {\x \\x} $reply_data]
+    gdb_assert { ![string equal "$reply_data" ""] }
+
+    # Run the test, fetches the auxv data in Python and confirm it
+    # matches the expected results.
+    gdb_test "python run_auxv_send_packet_test(\"$reply_data\")" \
+	"auxv send packet test passed"
+}
+
+set sizeof_global_var [get_valueof "/d" "sizeof(global_var)" "UNKNOWN"]
+if { $sizeof_global_var == 4 } {
+    gdb_test_no_output "set debug remote 1"
+    gdb_test "python run_set_global_var_test()" \
+	"set global_var test passed"
+}
diff --git a/gdb/testsuite/gdb.python/py-send-packet.py b/gdb/testsuite/gdb.python/py-send-packet.py
new file mode 100644
index 0000000..23abc42
--- /dev/null
+++ b/gdb/testsuite/gdb.python/py-send-packet.py
@@ -0,0 +1,176 @@
+# Copyright (C) 2021 Free Software Foundation, Inc.
+
+# 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 3 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, see <http://www.gnu.org/licenses/>.
+
+import xml.etree.ElementTree as ET
+import gdb
+
+# Make use of gdb.RemoteTargetConnection.send_packet to fetch the
+# thread list from the remote target.
+#
+# Sending existing serial protocol packets like this is not a good
+# idea, there should be better ways to get this information using an
+# official API, this is just being used as a test case.
+#
+# Really, the send_packet API would be used to send target
+# specific packets to the target, but these are, by definition, target
+# specific, so hard to test in a general testsuite.
+def get_thread_list_str():
+    start_pos = 0
+    thread_desc = ""
+    conn = gdb.selected_inferior().connection
+    if not isinstance(conn, gdb.RemoteTargetConnection):
+        raise gdb.GdbError("connection is the wrong type")
+    while True:
+        str = conn.send_packet("qXfer:threads:read::%d,200" % start_pos).decode("ascii")
+        start_pos += 200
+        c = str[0]
+        str = str[1:]
+        thread_desc += str
+        if c == "l":
+            break
+    return thread_desc
+
+
+# Use gdb.RemoteTargetConnection.send_packet to manually fetch the
+# thread list, then extract the thread list using the gdb.Inferior and
+# gdb.InferiorThread API.  Compare the two results to ensure we
+# managed to successfully read the thread list from the remote.
+def run_send_packet_test():
+    # Find the IDs of all current threads.
+    all_threads = {}
+    for inf in gdb.inferiors():
+        for thr in inf.threads():
+            id = "p%x.%x" % (thr.ptid[0], thr.ptid[1])
+            all_threads[id] = False
+
+    # Now fetch the thread list from the remote, and parse the XML.
+    str = get_thread_list_str()
+    threads_xml = ET.fromstring(str)
+
+    # Look over all threads in the XML list and check we expected to
+    # find them, mark the ones we do find.
+    for thr in threads_xml:
+        id = thr.get("id")
+        if not id in all_threads:
+            raise "found unexpected thread in remote thread list"
+        else:
+            all_threads[id] = True
+
+    # Check that all the threads were found in the XML list.
+    for id in all_threads:
+        if not all_threads[id]:
+            raise "thread missingt from remote thread list"
+
+    # Test complete.
+    print("Send packet test passed")
+
+
+# Convert a bytes object to a string.  This follows the same rules as
+# the 'maint packet' command so that the output from the two sources
+# can be compared.
+def bytes_to_string(byte_array):
+
+    # Python 2/3 compatibility.  We need a function that can give us
+    # the value of a single element in BYTE_ARRAY as an integer.
+    if sys.version_info[0] > 2:
+        value_of_single_byte = int
+    else:
+        value_of_single_byte = ord
+
+    res = ""
+    for b in byte_array:
+        b = value_of_single_byte(b)
+        if b >= 32 and b <= 126:
+            res = res + ("%c" % b)
+        else:
+            res = res + ("\\x%02x" % b)
+    return res
+
+
+# A very simple test for sending the packet that reads the auxv data.
+# We convert the result to a string and expect to find some
+# hex-encoded bytes in the output.  This test will only work on
+# targets that actually supply auxv data.
+def run_auxv_send_packet_test(expected_result):
+    inf = gdb.selected_inferior()
+    conn = inf.connection
+    assert isinstance(conn, gdb.RemoteTargetConnection)
+    res = conn.send_packet("qXfer:auxv:read::0,1000")
+    assert isinstance(res, bytes)
+    string = bytes_to_string(res)
+    assert string.count("\\x") > 0
+    assert string == expected_result
+    print("auxv send packet test passed")
+
+
+# Check that the value of 'global_var' is EXPECTED_VAL.
+def check_global_var(expected_val):
+    val = int(gdb.parse_and_eval("global_var"))
+    val = val & 0xFFFFFFFF
+    if val != expected_val:
+        raise gdb.GdbError("global_var is 0x%x, expected 0x%x" % (val, expected_val))
+
+
+# Set the 'X' packet to the remote target to set a global variable.
+# Checks that we can send byte values.
+def run_set_global_var_test():
+    inf = gdb.selected_inferior()
+    conn = inf.connection
+    assert isinstance(conn, gdb.RemoteTargetConnection)
+    addr = gdb.parse_and_eval("&global_var")
+    res = conn.send_packet("X%x,4:\x01\x01\x01\x01" % addr)
+    assert isinstance(res, bytes)
+    check_global_var(0x01010101)
+    res = conn.send_packet(b"X%x,4:\x02\x02\x02\x02" % addr)
+    assert isinstance(res, bytes)
+    check_global_var(0x02020202)
+    if sys.version_info[0] > 2:
+        # On Python 3 this first attempt will not work as we're
+        # passing a Unicode string containing non-ascii characters.
+        saw_error = False
+        try:
+            res = conn.send_packet("X%x,4:\xff\xff\xff\xff" % addr)
+        except UnicodeError:
+            saw_error = True
+        except:
+            assert False
+        assert saw_error
+        check_global_var(0x02020202)
+        # Now we pass a bytes object, which will work.
+        res = conn.send_packet(b"X%x,4:\xff\xff\xff\xff" % addr)
+        check_global_var(0xFFFFFFFF)
+    else:
+        # On Python 2 we need to force the creation of a Unicode
+        # string, but, with that done, we expect to see the same error
+        # as on Python 3; the unicode string contains non-ascii
+        # characters.
+        saw_error = False
+        try:
+            res = conn.send_packet(unicode("X%x,4:\xff\xff\xff\xff") % addr)
+        except UnicodeError:
+            saw_error = True
+        except:
+            assert False
+        assert saw_error
+        check_global_var(0x02020202)
+        # Now we pass a plain string, which, on Python 2, is the same
+        # as a bytes object, this, we expect to work.
+        res = conn.send_packet("X%x,4:\xff\xff\xff\xff" % addr)
+        check_global_var(0xFFFFFFFF)
+    print("set global_var test passed")
+
+
+# Just to indicate the file was sourced correctly.
+print("Sourcing complete.")