usb_request: USB transaction decoder and PCAP generator

The new decoder stacks on top of the usb_packet PD. It adds one new
annotation row, and is able to save the decoded data as PCAP trace.

It has been successfully tested against all traces in sigrok-dumps and
some more traces.

2 files changed, 395 insertions, 0 deletions

diff --git a/decoders/usb_request/__init__.py b/decoders/usb_request/__init__.py
new file mode 100644
index 0000000..7a156ff
--- /dev/null
+++ b/decoders/usb_request/__init__.py
@@ -0,0 +1,50 @@
+##
+## This file is part of the libsigrokdecode project.
+##
+## Copyright (C) 2015 Stefan Brüns <stefan.bruens@rwth-aachen.de>
+##
+## 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., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+##
+
+'''
+This decoder stacks on top of the 'usb_packet' PD and decodes the USB
+(low-speed and full-speed) transactions.
+
+Transactions and requests are tracked per device address and endpoint.
+
+Tracking of CONTROL requests is quite accurate, as these always start with
+a SETUP token and are completed by an IN or OUT transaction, the status
+packet. All transactions during the DATA stage are combined.
+
+For BULK and INTERRUPT requests, each transaction starts with an IN or OUT
+request, and is considered completed after the first transaction containing
+data has been ACKed. Normally a request is only completed after a short or
+zero length packet, but this would require knowledge about the max packet
+size of an endpoint.
+
+All INTERRUPT requests are treated as BULK requests, as on the link layer
+both are identical.
+
+The PCAP binary output contains 'SUBMIT' and 'COMPLETE' records. For
+CONTROL request, the SUBMIT contains the SETUP request, the data is
+either contained in the SUBMIT (Host-to-Device) or the COMPLETE
+(Device-to-Host) record.
+
+Details:
+https://en.wikipedia.org/wiki/USB
+http://www.usb.org/developers/docs/
+'''
+
+from .pd import Decoder
diff --git a/decoders/usb_request/pd.py b/decoders/usb_request/pd.py
new file mode 100644
index 0000000..060929b
--- /dev/null
+++ b/decoders/usb_request/pd.py
@@ -0,0 +1,345 @@
+##
+## This file is part of the libsigrokdecode project.
+##
+## Copyright (C) 2015 Stefan Brüns <stefan.bruens@rwth-aachen.de>
+##
+## 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., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+##
+
+import sigrokdecode as srd
+import struct
+
+class SamplerateError(Exception):
+    pass
+
+class pcap_usb_pkt():
+    # Linux usbmon format, see Documentation/usb/usbmon.txt
+    h  = b'\x00\x00\x00\x00' # ID part 1
+    h += b'\x00\x00\x00\x00' # ID part 2
+    h += b'C'                # 'S'ubmit / 'C'omplete / 'E'rror
+    h += b'\x03'             # ISO (0), Intr, Control, Bulk (3)
+    h += b'\x00'             # Endpoint
+    h += b'\x00'             # Device address
+    h += b'\x00\x00'         # Bus number
+    h += b'-'                # Setup tag - 0: Setup present, '-' otherwise
+    h += b'<'                # Data tag - '<' no data, 0 otherwise
+    # Timestamp
+    h += b'\x00\x00\x00\x00' # TS seconds part 1
+    h += b'\x00\x00\x00\x00' # TS seconds part 2
+    h += b'\x00\x00\x00\x00' # TS useconds
+    #
+    h += b'\x00\x00\x00\x00' # Status 0: OK
+    h += b'\x00\x00\x00\x00' # URB length
+    h += b'\x00\x00\x00\x00' # Data length
+    # Setup packet data, valid if setup tag == 0
+    h += b'\x00'             # bmRequestType
+    h += b'\x00'             # bRequest
+    h += b'\x00\x00'         # wValue
+    h += b'\x00\x00'         # wIndex
+    h += b'\x00\x00'         # wLength
+    #
+    h += b'\x00\x00\x00\x00' # ISO/interrupt interval
+    h += b'\x00\x00\x00\x00' # ISO start frame
+    h += b'\x00\x00\x00\x00' # URB flags
+    h += b'\x00\x00\x00\x00' # Number of ISO descriptors
+
+    def __init__(self, req, ts, is_submit):
+        self.header = bytearray(pcap_usb_pkt.h)
+        self.data = b''
+        self.set_urbid(req['id'])
+        self.set_urbtype('S' if is_submit else 'C')
+        self.set_timestamp(ts)
+        self.set_addr_ep(req['addr'], req['ep'])
+        if req['type'] in ('SETUP IN', 'SETUP OUT'):
+            self.set_transfertype(2) # Control
+            self.set_setup(req['setup_data'])
+        if req['type'] in ('BULK IN'):
+            self.set_addr_ep(req['addr'], 0x80 | req['ep'])
+        self.set_data(req['data'])
+
+    def set_urbid(self, urbid):
+        self.header[4:8] = struct.pack('>I', urbid)
+
+    def set_urbtype(self, urbtype):
+        self.header[8] = ord(urbtype)
+
+    def set_transfertype(self, transfertype):
+        self.header[9] = transfertype
+
+    def set_addr_ep(self, addr, ep):
+        self.header[11] = addr
+        self.header[10] = ep
+
+    def set_timestamp(self, ts):
+        self.timestamp = ts
+        self.header[20:24] = struct.pack('>I', ts[0]) # seconds
+        self.header[24:28] = struct.pack('>I', ts[1]) # microseconds
+
+    def set_data(self, data):
+        self.data = data
+        self.header[15] = 0
+        self.header[36:40] = struct.pack('>I', len(data))
+
+    def set_setup(self, data):
+        self.header[14] = 0
+        self.header[40:48] = data
+
+    def packet(self):
+        return bytes(self.header) + bytes(self.data)
+
+    def record_header(self):
+        # See https://wiki.wireshark.org/Development/LibpcapFileFormat.
+        (secs, usecs) = self.timestamp
+        h  = struct.pack('>I', secs) # TS seconds
+        h += struct.pack('>I', usecs) # TS microseconds
+        # No truncation, so both lengths are the same.
+        h += struct.pack('>I', len(self)) # Captured len (usb hdr + data)
+        h += struct.pack('>I', len(self)) # Original len
+        return h
+
+    def __len__(self):
+        return 64 + len(self.data)
+
+class Decoder(srd.Decoder):
+    api_version = 2
+    id = 'usb_request'
+    name = 'USB request'
+    longname = 'Universal Serial Bus (LS/FS) transaction/request'
+    desc = 'USB (low-speed and full-speed) transaction/request protocol.'
+    license = 'gplv2+'
+    inputs = ['usb_packet']
+    outputs = ['usb_request']
+    annotations = (
+        ('request-setup-read', 'Setup: Device-to-host'),
+        ('request-setup-write', 'Setup: Host-to-device'),
+        ('request-bulk-read', 'Bulk: Device-to-host'),
+        ('request-bulk-write', 'Bulk: Host-to-device'),
+        ('errors', 'Unexpected packets'),
+    )
+    annotation_rows = (
+        ('request', 'USB requests', tuple(range(4))),
+        ('errors', 'Errors', (4,)),
+    )
+    binary = (
+        ('pcap', 'PCAP format'),
+    )
+
+    def __init__(self):
+        self.samplerate = 8e6 # None
+        self.secs_per_sample = float(1) / float(self.samplerate)
+        self.request = {}
+        self.request_id = 0
+        self.transaction_state = 'IDLE'
+        self.transaction_ss = None
+        self.transaction_es = None
+        self.transaction_ep = None
+        self.transaction_addr = None
+        self.wrote_pcap_header = False
+
+    def putr(self, ss, es, data):
+        self.put(ss, es, self.out_ann, data)
+
+    def putb(self, ts, data):
+        self.put(ts, ts, self.out_bin, data)
+
+    def pcap_global_header(self):
+        # See https://wiki.wireshark.org/Development/LibpcapFileFormat.
+        h  = b'\xa1\xb2\xc3\xd4' # Magic, indicate microsecond ts resolution
+        h += b'\x00\x02'         # Major version 2
+        h += b'\x00\x04'         # Minor version 4
+        h += b'\x00\x00\x00\x00' # Correction vs. UTC, seconds
+        h += b'\x00\x00\x00\x00' # Timestamp accuracy
+        h += b'\xff\xff\xff\xff' # Max packet len
+        # LINKTYPE_USB_LINUX_MMAPPED 220
+        # Linux usbmon format, see Documentation/usb/usbmon.txt.
+        h += b'\x00\x00\x00\xdc' # Link layer
+        return h
+
+    def metadata(self, key, value):
+        if key == srd.SRD_CONF_SAMPLERATE:
+            self.samplerate = value
+            self.secs_per_sample = float(1) / float(self.samplerate)
+
+    def start(self):
+        self.out_bin = self.register(srd.OUTPUT_BINARY)
+        self.out_ann = self.register(srd.OUTPUT_ANN)
+
+    def handle_transfer(self):
+        request_started = 0
+        request_end = self.handshake in ('ACK', 'STALL')
+        ep = self.transaction_ep
+        addr = self.transaction_addr
+        if not (addr, ep) in self.request:
+            self.request[(addr, ep)] = {'setup_data': [], 'data': [],
+                'type': None, 'ss': self.transaction_ss, 'es': None,
+                'id': self.request_id, 'addr': addr, 'ep': ep}
+            self.request_id += 1
+            request_started = 1
+        request = self.request[(addr,ep)]
+
+        # BULK or INTERRUPT transfer
+        if request['type'] in (None, 'BULK IN') and self.transaction_type == 'IN':
+            request['type'] = 'BULK IN'
+            request['data'] += self.transaction_data
+            request['es'] = self.transaction_es
+            self.handle_request(request_started, request_end)
+        elif request['type'] in (None, 'BULK OUT') and self.transaction_type == 'OUT':
+            request['type'] = 'BULK OUT'
+            request['data'] += self.transaction_data
+            request['es'] = self.transaction_es
+            self.handle_request(request_started, request_end)
+
+        # CONTROL, SETUP stage
+        elif request['type'] == None and self.transaction_type == 'SETUP':
+            request['setup_data'] = self.transaction_data
+            request['wLength'] = struct.unpack('<H',
+                bytes(self.transaction_data[6:8]))[0]
+            if self.transaction_data[0] & 0x80:
+                request['type'] = 'SETUP IN'
+                self.handle_request(1, 0)
+            else:
+                request['type'] = 'SETUP OUT'
+                self.handle_request(request['wLength'] == 0, 0)
+
+        # CONTROL, DATA stage
+        elif request['type'] == 'SETUP IN' and self.transaction_type == 'IN':
+            request['data'] += self.transaction_data
+
+        elif request['type'] == 'SETUP OUT' and self.transaction_type == 'OUT':
+            request['data'] += self.transaction_data
+            if request['wLength'] == len(request['data']):
+                self.handle_request(1, 0)
+
+        # CONTROL, STATUS stage
+        elif request['type'] == 'SETUP IN' and self.transaction_type == 'OUT':
+            request['es'] = self.transaction_es
+            self.handle_request(0, request_end)
+
+        elif request['type'] == 'SETUP OUT' and self.transaction_type == 'IN':
+            request['es'] = self.transaction_es
+            self.handle_request(0, request_end)
+
+        else:
+            return
+
+        return
+
+    def ts_from_samplenum(self, sample):
+        ts = float(sample) * self.secs_per_sample
+        return (int(ts), int((ts % 1.0) * 1e6))
+
+    def write_pcap_header(self):
+        if not self.wrote_pcap_header:
+            self.put(0, 0, self.out_bin, (0, self.pcap_global_header()))
+            self.wrote_pcap_header = True
+
+    def request_summary(self, request):
+        s = '['
+        if request['type'] in ('SETUP IN', 'SETUP OUT'):
+            for b in request['setup_data']:
+                s += ' %02X' % b
+            s += ' ]['
+        for b in request['data']:
+            s += ' %02X' % b
+        s += ' ] : %s' % self.handshake
+        return s
+
+    def handle_request(self, request_start, request_end):
+        if request_start != 1 and request_end != 1:
+            return
+        self.write_pcap_header()
+        ep = self.transaction_ep
+        addr = self.transaction_addr
+        request = self.request[(addr, ep)]
+
+        ss, es = request['ss'], request['es']
+
+        if request_start == 1:
+            # Issue PCAP 'SUBMIT' packet.
+            ts = self.ts_from_samplenum(ss)
+            pkt = pcap_usb_pkt(request, ts, True)
+            self.putb(ss, (0, pkt.record_header()))
+            self.putb(ss, (0, pkt.packet()))
+
+        if request_end == 1:
+            # Write annotation.
+            summary = self.request_summary(request)
+            if request['type'] == 'SETUP IN':
+                self.putr(ss, es, [0, ['SETUP in: %s' % summary]])
+            elif request['type'] == 'SETUP OUT':
+                self.putr(ss, es, [1, ['SETUP out: %s' % summary]])
+            elif request['type'] == 'BULK IN':
+                self.putr(ss, es, [2, ['BULK in: %s' % summary]])
+            elif request['type'] == 'BULK OUT':
+                self.putr(ss, es, [3, ['BULK out: %s' % summary]])
+
+            # Issue PCAP 'COMPLETE' packet.
+            ts = self.ts_from_samplenum(es)
+            pkt = pcap_usb_pkt(request, ts, False)
+            self.putb(ss, (0, pkt.record_header()))
+            self.putb(ss, (0, pkt.packet()))
+            del self.request[(addr, ep)]
+
+    def decode(self, ss, es, data):
+        if not self.samplerate:
+            raise SamplerateError('Cannot decode without samplerate.')
+        ptype, pdata = data
+
+        # We only care about certain packet types for now.
+        if ptype not in ('PACKET'):
+            return
+
+        pcategory, pname, pinfo = pdata
+
+        if pcategory == 'TOKEN':
+            if pname == 'SOF':
+                return
+            if self.transaction_state != 'IDLE':
+                self.putr(ss, es, [4, ['ERR: received %s token in state %s' %
+                    (pname, self.transaction_state)]])
+                return
+
+            sync, pid, addr, ep, crc5 = pinfo
+            self.transaction_data = []
+            self.transaction_ss = ss
+            self.transaction_state = 'TOKEN RECEIVED'
+            self.transaction_ep = ep
+            self.transaction_addr = addr
+            self.transaction_type = pname # IN OUT SETUP
+
+        elif pcategory == 'DATA':
+            if self.transaction_state != 'TOKEN RECEIVED':
+                self.putr(ss, es, [4, ['ERR: received %s token in state %s' %
+                    (pname, self.transaction_state)]])
+                return
+
+            self.transaction_data = pinfo[2]
+            self.transaction_state = 'DATA RECEIVED'
+
+        elif pcategory == 'HANDSHAKE':
+            if self.transaction_state not in ('TOKEN RECEIVED', 'DATA RECEIVED'):
+                self.putr(ss, es, [4, ['ERR: received %s token in state %s' %
+                    (pname, self.transaction_state)]])
+                return
+
+            self.handshake = pname
+            self.transaction_state = 'IDLE'
+            self.transaction_es = es
+            self.handle_transfer()
+
+        else:
+            self.putr(ss, es, [4, ['ERR: received unhandled %s token in state %s' %
+                (pname, self.transaction_state)]])
+            return