decoders/usb_request/pd.py

   1 ##
   2 ## This file is part of the libsigrokdecode project.
   3 ##
   4 ## Copyright (C) 2015 Stefan Brüns <stefan.bruens@rwth-aachen.de>
   5 ##
   6 ## This program is free software; you can redistribute it and/or modify
   7 ## it under the terms of the GNU General Public License as published by
   8 ## the Free Software Foundation; either version 2 of the License, or
   9 ## (at your option) any later version.
  10 ##
  11 ## This program is distributed in the hope that it will be useful,
  12 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 ## GNU General Public License for more details.
  15 ##
  16 ## You should have received a copy of the GNU General Public License
  17 ## along with this program; if not, write to the Free Software
  18 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  19 ##
  20
  21 import sigrokdecode as srd
  22 import struct
  23
  24 class SamplerateError(Exception):
  25     pass
  26
  27 class pcap_usb_pkt():
  28     # Linux usbmon format, see Documentation/usb/usbmon.txt
  29     h  = b'\x00\x00\x00\x00' # ID part 1
  30     h += b'\x00\x00\x00\x00' # ID part 2
  31     h += b'C'                # 'S'ubmit / 'C'omplete / 'E'rror
  32     h += b'\x03'             # ISO (0), Intr, Control, Bulk (3)
  33     h += b'\x00'             # Endpoint
  34     h += b'\x00'             # Device address
  35     h += b'\x00\x00'         # Bus number
  36     h += b'-'                # Setup tag - 0: Setup present, '-' otherwise
  37     h += b'<'                # Data tag - '<' no data, 0 otherwise
  38     # Timestamp
  39     h += b'\x00\x00\x00\x00' # TS seconds part 1
  40     h += b'\x00\x00\x00\x00' # TS seconds part 2
  41     h += b'\x00\x00\x00\x00' # TS useconds
  42     #
  43     h += b'\x00\x00\x00\x00' # Status 0: OK
  44     h += b'\x00\x00\x00\x00' # URB length
  45     h += b'\x00\x00\x00\x00' # Data length
  46     # Setup packet data, valid if setup tag == 0
  47     h += b'\x00'             # bmRequestType
  48     h += b'\x00'             # bRequest
  49     h += b'\x00\x00'         # wValue
  50     h += b'\x00\x00'         # wIndex
  51     h += b'\x00\x00'         # wLength
  52     #
  53     h += b'\x00\x00\x00\x00' # ISO/interrupt interval
  54     h += b'\x00\x00\x00\x00' # ISO start frame
  55     h += b'\x00\x00\x00\x00' # URB flags
  56     h += b'\x00\x00\x00\x00' # Number of ISO descriptors
  57
  58     def __init__(self, req, ts, is_submit):
  59         self.header = bytearray(pcap_usb_pkt.h)
  60         self.data = b''
  61         self.set_urbid(req['id'])
  62         self.set_urbtype('S' if is_submit else 'C')
  63         self.set_timestamp(ts)
  64         self.set_addr_ep(req['addr'], req['ep'])
  65         if req['type'] in ('SETUP IN', 'SETUP OUT'):
  66             self.set_transfertype(2) # Control
  67             self.set_setup(req['setup_data'])
  68         if req['type'] in ('BULK IN'):
  69             self.set_addr_ep(req['addr'], 0x80 | req['ep'])
  70         self.set_data(req['data'])
  71
  72     def set_urbid(self, urbid):
  73         self.header[4:8] = struct.pack('>I', urbid)
  74
  75     def set_urbtype(self, urbtype):
  76         self.header[8] = ord(urbtype)
  77
  78     def set_transfertype(self, transfertype):
  79         self.header[9] = transfertype
  80
  81     def set_addr_ep(self, addr, ep):
  82         self.header[11] = addr
  83         self.header[10] = ep
  84
  85     def set_timestamp(self, ts):
  86         self.timestamp = ts
  87         self.header[20:24] = struct.pack('>I', ts[0]) # seconds
  88         self.header[24:28] = struct.pack('>I', ts[1]) # microseconds
  89
  90     def set_data(self, data):
  91         self.data = data
  92         self.header[15] = 0
  93         self.header[36:40] = struct.pack('>I', len(data))
  94
  95     def set_setup(self, data):
  96         self.header[14] = 0
  97         self.header[40:48] = data
  98
  99     def packet(self):
 100         return bytes(self.header) + bytes(self.data)
 101
 102     def record_header(self):
 103         # See https://wiki.wireshark.org/Development/LibpcapFileFormat.
 104         (secs, usecs) = self.timestamp
 105         h  = struct.pack('>I', secs) # TS seconds
 106         h += struct.pack('>I', usecs) # TS microseconds
 107         # No truncation, so both lengths are the same.
 108         h += struct.pack('>I', len(self)) # Captured len (usb hdr + data)
 109         h += struct.pack('>I', len(self)) # Original len
 110         return h
 111
 112     def __len__(self):
 113         return 64 + len(self.data)
 114
 115 class Decoder(srd.Decoder):
 116     api_version = 2
 117     id = 'usb_request'
 118     name = 'USB request'
 119     longname = 'Universal Serial Bus (LS/FS) transaction/request'
 120     desc = 'USB (low-speed and full-speed) transaction/request protocol.'
 121     license = 'gplv2+'
 122     inputs = ['usb_packet']
 123     outputs = ['usb_request']
 124     annotations = (
 125         ('request-setup-read', 'Setup: Device-to-host'),
 126         ('request-setup-write', 'Setup: Host-to-device'),
 127         ('request-bulk-read', 'Bulk: Device-to-host'),
 128         ('request-bulk-write', 'Bulk: Host-to-device'),
 129         ('errors', 'Unexpected packets'),
 130     )
 131     annotation_rows = (
 132         ('request', 'USB requests', tuple(range(4))),
 133         ('errors', 'Errors', (4,)),
 134     )
 135     binary = (
 136         ('pcap', 'PCAP format'),
 137     )
 138
 139     def __init__(self):
 140         self.samplerate = 8e6 # None
 141         self.secs_per_sample = float(1) / float(self.samplerate)
 142         self.request = {}
 143         self.request_id = 0
 144         self.transaction_state = 'IDLE'
 145         self.transaction_ss = None
 146         self.transaction_es = None
 147         self.transaction_ep = None
 148         self.transaction_addr = None
 149         self.wrote_pcap_header = False
 150
 151     def putr(self, ss, es, data):
 152         self.put(ss, es, self.out_ann, data)
 153
 154     def putb(self, ts, data):
 155         self.put(ts, ts, self.out_bin, data)
 156
 157     def pcap_global_header(self):
 158         # See https://wiki.wireshark.org/Development/LibpcapFileFormat.
 159         h  = b'\xa1\xb2\xc3\xd4' # Magic, indicate microsecond ts resolution
 160         h += b'\x00\x02'         # Major version 2
 161         h += b'\x00\x04'         # Minor version 4
 162         h += b'\x00\x00\x00\x00' # Correction vs. UTC, seconds
 163         h += b'\x00\x00\x00\x00' # Timestamp accuracy
 164         h += b'\xff\xff\xff\xff' # Max packet len
 165         # LINKTYPE_USB_LINUX_MMAPPED 220
 166         # Linux usbmon format, see Documentation/usb/usbmon.txt.
 167         h += b'\x00\x00\x00\xdc' # Link layer
 168         return h
 169
 170     def metadata(self, key, value):
 171         if key == srd.SRD_CONF_SAMPLERATE:
 172             self.samplerate = value
 173             self.secs_per_sample = float(1) / float(self.samplerate)
 174
 175     def start(self):
 176         self.out_bin = self.register(srd.OUTPUT_BINARY)
 177         self.out_ann = self.register(srd.OUTPUT_ANN)
 178
 179     def handle_transfer(self):
 180         request_started = 0
 181         request_end = self.handshake in ('ACK', 'STALL')
 182         ep = self.transaction_ep
 183         addr = self.transaction_addr
 184         if not (addr, ep) in self.request:
 185             self.request[(addr, ep)] = {'setup_data': [], 'data': [],
 186                 'type': None, 'ss': self.transaction_ss, 'es': None,
 187                 'id': self.request_id, 'addr': addr, 'ep': ep}
 188             self.request_id += 1
 189             request_started = 1
 190         request = self.request[(addr,ep)]
 191
 192         # BULK or INTERRUPT transfer
 193         if request['type'] in (None, 'BULK IN') and self.transaction_type == 'IN':
 194             request['type'] = 'BULK IN'
 195             request['data'] += self.transaction_data
 196             request['es'] = self.transaction_es
 197             self.handle_request(request_started, request_end)
 198         elif request['type'] in (None, 'BULK OUT') and self.transaction_type == 'OUT':
 199             request['type'] = 'BULK OUT'
 200             request['data'] += self.transaction_data
 201             request['es'] = self.transaction_es
 202             self.handle_request(request_started, request_end)
 203
 204         # CONTROL, SETUP stage
 205         elif request['type'] == None and self.transaction_type == 'SETUP':
 206             request['setup_data'] = self.transaction_data
 207             request['wLength'] = struct.unpack('<H',
 208                 bytes(self.transaction_data[6:8]))[0]
 209             if self.transaction_data[0] & 0x80:
 210                 request['type'] = 'SETUP IN'
 211                 self.handle_request(1, 0)
 212             else:
 213                 request['type'] = 'SETUP OUT'
 214                 self.handle_request(request['wLength'] == 0, 0)
 215
 216         # CONTROL, DATA stage
 217         elif request['type'] == 'SETUP IN' and self.transaction_type == 'IN':
 218             request['data'] += self.transaction_data
 219
 220         elif request['type'] == 'SETUP OUT' and self.transaction_type == 'OUT':
 221             request['data'] += self.transaction_data
 222             if request['wLength'] == len(request['data']):
 223                 self.handle_request(1, 0)
 224
 225         # CONTROL, STATUS stage
 226         elif request['type'] == 'SETUP IN' and self.transaction_type == 'OUT':
 227             request['es'] = self.transaction_es
 228             self.handle_request(0, request_end)
 229
 230         elif request['type'] == 'SETUP OUT' and self.transaction_type == 'IN':
 231             request['es'] = self.transaction_es
 232             self.handle_request(0, request_end)
 233
 234         else:
 235             return
 236
 237         return
 238
 239     def ts_from_samplenum(self, sample):
 240         ts = float(sample) * self.secs_per_sample
 241         return (int(ts), int((ts % 1.0) * 1e6))
 242
 243     def write_pcap_header(self):
 244         if not self.wrote_pcap_header:
 245             self.put(0, 0, self.out_bin, (0, self.pcap_global_header()))
 246             self.wrote_pcap_header = True
 247
 248     def request_summary(self, request):
 249         s = '['
 250         if request['type'] in ('SETUP IN', 'SETUP OUT'):
 251             for b in request['setup_data']:
 252                 s += ' %02X' % b
 253             s += ' ]['
 254         for b in request['data']:
 255             s += ' %02X' % b
 256         s += ' ] : %s' % self.handshake
 257         return s
 258
 259     def handle_request(self, request_start, request_end):
 260         if request_start != 1 and request_end != 1:
 261             return
 262         self.write_pcap_header()
 263         ep = self.transaction_ep
 264         addr = self.transaction_addr
 265         request = self.request[(addr, ep)]
 266
 267         ss, es = request['ss'], request['es']
 268
 269         if request_start == 1:
 270             # Issue PCAP 'SUBMIT' packet.
 271             ts = self.ts_from_samplenum(ss)
 272             pkt = pcap_usb_pkt(request, ts, True)
 273             self.putb(ss, (0, pkt.record_header()))
 274             self.putb(ss, (0, pkt.packet()))
 275
 276         if request_end == 1:
 277             # Write annotation.
 278             summary = self.request_summary(request)
 279             if request['type'] == 'SETUP IN':
 280                 self.putr(ss, es, [0, ['SETUP in: %s' % summary]])
 281             elif request['type'] == 'SETUP OUT':
 282                 self.putr(ss, es, [1, ['SETUP out: %s' % summary]])
 283             elif request['type'] == 'BULK IN':
 284                 self.putr(ss, es, [2, ['BULK in: %s' % summary]])
 285             elif request['type'] == 'BULK OUT':
 286                 self.putr(ss, es, [3, ['BULK out: %s' % summary]])
 287
 288             # Issue PCAP 'COMPLETE' packet.
 289             ts = self.ts_from_samplenum(es)
 290             pkt = pcap_usb_pkt(request, ts, False)
 291             self.putb(ss, (0, pkt.record_header()))
 292             self.putb(ss, (0, pkt.packet()))
 293             del self.request[(addr, ep)]
 294
 295     def decode(self, ss, es, data):
 296         if not self.samplerate:
 297             raise SamplerateError('Cannot decode without samplerate.')
 298         ptype, pdata = data
 299
 300         # We only care about certain packet types for now.
 301         if ptype not in ('PACKET'):
 302             return
 303
 304         pcategory, pname, pinfo = pdata
 305
 306         if pcategory == 'TOKEN':
 307             if pname == 'SOF':
 308                 return
 309             if self.transaction_state != 'IDLE':
 310                 self.putr(ss, es, [4, ['ERR: received %s token in state %s' %
 311                     (pname, self.transaction_state)]])
 312                 return
 313
 314             sync, pid, addr, ep, crc5 = pinfo
 315             self.transaction_data = []
 316             self.transaction_ss = ss
 317             self.transaction_state = 'TOKEN RECEIVED'
 318             self.transaction_ep = ep
 319             self.transaction_addr = addr
 320             self.transaction_type = pname # IN OUT SETUP
 321
 322         elif pcategory == 'DATA':
 323             if self.transaction_state != 'TOKEN RECEIVED':
 324                 self.putr(ss, es, [4, ['ERR: received %s token in state %s' %
 325                     (pname, self.transaction_state)]])
 326                 return
 327
 328             self.transaction_data = pinfo[2]
 329             self.transaction_state = 'DATA RECEIVED'
 330
 331         elif pcategory == 'HANDSHAKE':
 332             if self.transaction_state not in ('TOKEN RECEIVED', 'DATA RECEIVED'):
 333                 self.putr(ss, es, [4, ['ERR: received %s token in state %s' %
 334                     (pname, self.transaction_state)]])
 335                 return
 336
 337             self.handshake = pname
 338             self.transaction_state = 'IDLE'
 339             self.transaction_es = es
 340             self.handle_transfer()
 341
 342         else:
 343             self.putr(ss, es, [4, ['ERR: received unhandled %s token in state %s' %
 344                 (pname, self.transaction_state)]])
 345             return