GDB: add implementation of remote protocol

GDB talks to targets via a so-called remote protocol. These targets
can be things like gdbserver, ROM monitors on specific hardware boards,
or applications that implement the same protocol.

One noteworthy example of application is QEMU, which implements some
basic GDB Remote commands and also a few extenions of its own.

This initial implementation allows connecting to the remote target,
sending commands and receive results. The API can certainly grow later
based on demand.

Changes from v1:
 * Fix a typo in the REMOTE_MAX_PACKET_SIZE comment
Signed-off-by: NCleber Rosa <crosa@redhat.com>

avocado/gdb.py

@@ -16,9 +16,13 @@
 Module that provides communication with GDB via its GDB/MI interpreter
 """
 
+__all__ = ['GDB', 'GDBServer', 'GDBRemote']
+
+
 import os
 import time
 import fcntl
+import socket
 import tempfile
 import subprocess
 
@@ -29,6 +33,24 @@ GDB_PROMPT = '(gdb)'
 GDB_EXIT = '^exit'
 GDB_BREAK_CONTITIONS = [GDB_PROMPT, GDB_EXIT]
 
+#: How the remote protocol signals a transmission success (in ACK mode)
+REMOTE_TRANSMISSION_SUCCESS = '+'
+
+#: How the remote protocol signals a transmission failure (in ACK mode)
+REMOTE_TRANSMISSION_FAILURE = '-'
+
+#: How the remote protocol flags the start of a packet
+REMOTE_PREFIX = '$'
+
+#: How the remote protocol flags the end of the packet payload, and that the
+#: two digits checksum follow
+REMOTE_DELIMITER = '#'
+
+#: Rather conservative default maximum packet size for clients using the
+#: remote protocol. Individual connections can ask (and do so by default)
+#: the server about the maximum packet size they can handle.
+REMOTE_MAX_PACKET_SIZE = 1024
+
 
 class UnexpectedResponseError(Exception):
 
@@ -46,6 +68,30 @@ class ServerInitTimeoutError(Exception):
     pass
 
 
+class InvalidPacketError(Exception):
+
+    '''
+    Packet received has invalid format
+    '''
+    pass
+
+
+class NotConnectedError(Exception):
+
+    '''
+    GDBRemote is not connected to a remote GDB server
+    '''
+    pass
+
+
+class RetransmissionRequestedError(Exception):
+
+    '''
+    Message integrity was not validated and retransmission is being requested
+    '''
+    pass
+
+
 def parse_mi(line):
     '''
     Parse a GDB/MI line
@@ -132,6 +178,91 @@ def is_fatal_signal(parsed_mi_msg):
     return is_sigsegv(parsed_mi_msg) or is_sigabrt(parsed_mi_msg)
 
 
+def format_as_hex(char):
+    """
+    Formats a single ascii character as a lower case hex string
+
+    :param char: a single ascii character
+    :type char: str
+    :returns: the character formatted as a lower case hex string
+    :rtype: str
+    """
+    return "%2x" % ord(char)
+
+
+def string_to_hex(text):
+    """
+    Formats a string of text into an hex representation
+
+    :param text: a multi character string
+    :type text: str
+    :returns: the string converted to an hex representation
+    :rtype: str
+    """
+    return "".join(map(format_as_hex, text))
+
+
+def remote_checksum(input):
+    '''
+    Calculates a remote message checksum
+
+    :param input: the message input payload, without the start and end markers
+    :type input: str
+    :returns: two digit checksum
+    :rtype: str
+    '''
+    sum = 0
+    for i in input:
+        sum += ord(i)
+    result = sum % 256
+
+    hexa = "%2x" % result
+    return hexa.lower()
+
+
+def remote_encode(data):
+    """
+    Encodes a command
+
+    That is, add prefix, suffix and checksum
+
+    :param command_data: the command data payload
+    :type command_data: str
+    :returns: the encoded command, ready to be sent to a remote GDB
+    :rtype: str
+    """
+    return "$%s#%s" % (data, remote_checksum(data))
+
+
+def remote_decode(data):
+    """
+    Decodes a packet and returns its payload
+
+    :param command_data: the command data payload
+    :type command_data: str
+    :returns: the encoded command, ready to be sent to a remote GDB
+    :rtype: str
+    """
+    if data[0] != REMOTE_PREFIX:
+        raise InvalidPacketError
+
+    if data[-3] != REMOTE_DELIMITER:
+        raise InvalidPacketError
+
+    payload = data[1:-3]
+    checksum = data[-2:]
+
+    if payload == '':
+        expected_checksum = '00'
+    else:
+        expected_checksum = remote_checksum(payload)
+
+    if checksum != expected_checksum:
+        raise InvalidPacketError
+
+    return payload
+
+
 class CommandResult(object):
 
     """
@@ -551,3 +682,110 @@ class GDBServer(object):
             self.process.wait()
             self.stdout.close()
             self.stderr.close()
+
+
+class GDBRemote(object):
+
+    def __init__(self, host, port, no_ack_mode=True, extended_mode=True):
+        """
+        Initializes a new GDBRemote object.
+
+        A GDBRemote acts like a client that speaks the GDB remote protocol,
+        documented at:
+
+        https://sourceware.org/gdb/current/onlinedocs/gdb/Remote-Protocol.html
+
+        Caveat: we currently do not support communicating with devices, only
+        with TCP sockets. This limitation is basically due to the lack of
+        use cases that justify an implementation, but not due to any technical
+        shortcoming.
+
+        :param host: the IP address or host name
+        :type host: str
+        :param port: the port number where the the remote GDB is listening on
+        :type port: int
+        :param no_ack_mode: if the packet transmission confirmation mode should
+                            be disabled
+        :type no_ack_mode: bool
+        :param extended_mode: if the remote extended mode should be enabled
+        :type param extended_mode: bool
+        """
+        self.host = host
+        self.port = port
+
+        # Temporary holder for the class init attributes
+        self._no_ack_mode = no_ack_mode
+        self.no_ack_mode = False
+        self._extended_mode = extended_mode
+        self.extended_mode = False
+
+        self._socket = None
+
+    def cmd(self, command_data, expected_response=None):
+        """
+        Sends a command data to a remote gdb server
+
+        Limitations: the current version does not deal with retransmissions.
+
+        :param command_data: the remote command to send the the remote stub
+        :type command_data: str
+        :param expected_response: the (optional) response that is expected
+                                  as a response for the command sent
+        :type expected_response: str
+        :raises: RetransmissionRequestedError, UnexpectedResponseError
+        :returns: raw data read from from the remote server
+        :rtype: str
+        """
+        if self._socket is None:
+            raise NotConnectedError
+
+        data = remote_encode(command_data)
+        sent = self._socket.send(data)
+
+        if not self.no_ack_mode:
+            transmission_result = self._socket.recv(1)
+            if transmission_result == REMOTE_TRANSMISSION_FAILURE:
+                raise RetransmissionRequestedError
+
+        result = self._socket.recv(REMOTE_MAX_PACKET_SIZE)
+        response_payload = remote_decode(result)
+
+        if expected_response is not None:
+            if expected_response != response_payload:
+                raise UnexpectedResponseError
+
+        return response_payload
+
+    def set_extended_mode(self):
+        """
+        Enable extended mode. In extended mode, the remote server is made
+        persistent. The 'R' packet is used to restart the program being
+        debugged. Original documentation at:
+
+        https://sourceware.org/gdb/current/onlinedocs/gdb/Packets.html#extended-mode
+        """
+        self.cmd("!", "OK")
+        self.extended_mode = True
+
+    def start_no_ack_mode(self):
+        """
+        Request that the remote stub disable the normal +/- protocol
+        acknowledgments. Original documentation at:
+
+        https://sourceware.org/gdb/current/onlinedocs/gdb/General-Query-Packets.html#QStartNoAckMode
+        """
+        self.cmd("QStartNoAckMode", "OK")
+        self.no_ack_mode = True
+
+    def connect(self):
+        """
+        Connects to the remote target and initializes the chosen modes
+        """
+        self._socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self._socket.connect((self.host, self.port))
+
+        if self._no_ack_mode:
+            self.start_no_ack_mode()
+
+        if self._extended_mode:
+            self.set_extended_mode()

docs/source/DebuggingWithGDB.rst

 Debugging with GDB
 ==================
 
-Avocado has support for transparently debugging binaries inside the GNU
-Debugger. This means that any test that uses :mod:`avocado.utils.process`
+Avocado has two levels of GDB support, one by using the Avocado GDB APIs
+to fire up GDB and interact with it, and other by transparently debugging
+binaries inside the GNU Debugger based on command line only options. This
+later option means that any test that uses :mod:`avocado.utils.process`
 can transparently inspect processes during test run time.
 
-Usage
------
+API
+---
+
+Avocado's GDB module, provides three main classes that lets a test writer
+interact with a `gdb` process, a `gdbserver` process and also use the GDB
+remote protocol for interaction with a remote target.
+
+Please refer to :mod:`avocado.gdb` for more information.
+
+
+Transparent Debugging Usage
+---------------------------
 
 This feature is implemented as a plugin, that adds the `--gdb-run-bin` option
 to the avocado `run` command. For a detailed explanation please consult the
 avocado man page.
 
 Caveats
--------
+~~~~~~~
 
 Currently, when using the Avocado GDB plugin, that is, when using the
 `--gdb-run-bin` option, there are some caveats you should be aware of:

examples/tests/gdbtest.py

@@ -378,6 +378,17 @@ class gdbtest(test.Test):
         result = process.run(self.return99_binary_path, ignore_status=True)
         self.assertIn("return 99\n", result.stdout)
 
+    def test_remote(self):
+        """
+        Tests GDBRemote interaction with a GDBServer
+        """
+        s = gdb.GDBServer()
+        r = gdb.GDBRemote('127.0.0.1', s.port)
+        r.connect()
+        r.cmd("qSupported")
+        r.cmd("qfThreadInfo")
+        s.exit()
+
     def action(self):
         """
         Execute tests
@@ -402,3 +413,4 @@ class gdbtest(test.Test):
         self.test_server_stderr()
         self.test_server_stdout()
         self.test_interactive_stdout()
+        self.test_remote()

selftests/all/unit/avocado/gdb_unittest.py

+# 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 LICENSE for more details.
+#
+# Copyright: Red Hat Inc. 2014
+# Authors: Cleber Rosa <cleber@redhat.com>
+
+
+import os
+import sys
+import unittest
+
+# simple magic for using scripts within a source tree
+basedir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+basedir = os.path.dirname(basedir)
+if os.path.isdir(os.path.join(basedir, 'avocado')):
+    sys.path.append(basedir)
+
+
+from avocado import gdb
+
+
+class GDBRemoteTest(unittest.TestCase):
+
+    def test_checksum(self):
+        in_out = (('!', '21'),
+                  ('OK', '9A'),
+                  ('foo', '44'))
+        for io in in_out:
+            i, o = io
+            self.assertTrue(gdb.remote_checksum(i), o)
+
+    def test_encode_command(self):
+        in_out = (('!', '$!#21'),
+                  ('OK', '$OK#9a'),
+                  ('foo', '$foo#44'))
+        for io in in_out:
+            i, o = io
+            self.assertTrue(gdb.remote_encode(i), o)
+
+    def test_decode_response(self):
+        in_out = (('$!#21', '!'),
+                  ('$OK#9a', 'OK'),
+                  ('$foo#44', 'foo'))
+        for io in in_out:
+            i, o = io
+            self.assertTrue(gdb.remote_decode(i), o)
+
+    def test_decode_invalid(self):
+        invalid_packets = ['$!#22',
+                           '$foo$bar#21',
+                           '!!#21',
+                           '+$!#21']
+        for p in invalid_packets:
+            self.assertRaises(gdb.InvalidPacketError,
+                              gdb.remote_decode, p)
+
+
+if __name__ == '__main__':
+    unittest.main()