2 ## This file is part of the libsigrokdecode project.
4 ## Copyright (C) 2015 Stefan BrĂ¼ns <stefan.bruens@rwth-aachen.de>
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.
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.
16 ## You should have received a copy of the GNU General Public License
17 ## along with this program; if not, see <http://www.gnu.org/licenses/>.
20 import sigrokdecode as srd
23 class SamplerateError(Exception):
27 # Linux usbmon format, see Documentation/usb/usbmon.txt
28 h = b'\x00\x00\x00\x00' # ID part 1
29 h += b'\x00\x00\x00\x00' # ID part 2
30 h += b'C' # 'S'ubmit / 'C'omplete / 'E'rror
31 h += b'\x03' # ISO (0), Intr, Control, Bulk (3)
32 h += b'\x00' # Endpoint
33 h += b'\x00' # Device address
34 h += b'\x00\x00' # Bus number
35 h += b'-' # Setup tag - 0: Setup present, '-' otherwise
36 h += b'<' # Data tag - '<' no data, 0 otherwise
38 h += b'\x00\x00\x00\x00' # TS seconds part 1
39 h += b'\x00\x00\x00\x00' # TS seconds part 2
40 h += b'\x00\x00\x00\x00' # TS useconds
42 h += b'\x00\x00\x00\x00' # Status 0: OK
43 h += b'\x00\x00\x00\x00' # URB length
44 h += b'\x00\x00\x00\x00' # Data length
45 # Setup packet data, valid if setup tag == 0
46 h += b'\x00' # bmRequestType
47 h += b'\x00' # bRequest
48 h += b'\x00\x00' # wValue
49 h += b'\x00\x00' # wIndex
50 h += b'\x00\x00' # wLength
52 h += b'\x00\x00\x00\x00' # ISO/interrupt interval
53 h += b'\x00\x00\x00\x00' # ISO start frame
54 h += b'\x00\x00\x00\x00' # URB flags
55 h += b'\x00\x00\x00\x00' # Number of ISO descriptors
57 def __init__(self, req, ts, is_submit):
58 self.header = bytearray(pcap_usb_pkt.h)
60 self.set_urbid(req['id'])
61 self.set_urbtype('S' if is_submit else 'C')
62 self.set_timestamp(ts)
63 self.set_addr_ep(req['addr'], req['ep'])
64 if req['type'] in ('SETUP IN', 'SETUP OUT'):
65 self.set_transfertype(2) # Control
66 self.set_setup(req['setup_data'])
67 if req['type'] in ('BULK IN'):
68 self.set_addr_ep(req['addr'], 0x80 | req['ep'])
69 self.set_data(req['data'])
71 def set_urbid(self, urbid):
72 self.header[4:8] = struct.pack('>I', urbid)
74 def set_urbtype(self, urbtype):
75 self.header[8] = ord(urbtype)
77 def set_transfertype(self, transfertype):
78 self.header[9] = transfertype
80 def set_addr_ep(self, addr, ep):
81 self.header[11] = addr
84 def set_timestamp(self, ts):
86 self.header[20:24] = struct.pack('>I', ts[0]) # seconds
87 self.header[24:28] = struct.pack('>I', ts[1]) # microseconds
89 def set_data(self, data):
92 self.header[36:40] = struct.pack('>I', len(data))
94 def set_setup(self, data):
96 self.header[40:48] = data
99 return bytes(self.header) + bytes(self.data)
101 def record_header(self):
102 # See https://wiki.wireshark.org/Development/LibpcapFileFormat.
103 (secs, usecs) = self.timestamp
104 h = struct.pack('>I', secs) # TS seconds
105 h += struct.pack('>I', usecs) # TS microseconds
106 # No truncation, so both lengths are the same.
107 h += struct.pack('>I', len(self)) # Captured len (usb hdr + data)
108 h += struct.pack('>I', len(self)) # Original len
112 return 64 + len(self.data)
114 class Decoder(srd.Decoder):
118 longname = 'Universal Serial Bus (LS/FS) transaction/request'
119 desc = 'USB (low-speed/full-speed) transaction/request protocol.'
121 inputs = ['usb_packet']
122 outputs = ['usb_request']
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'),
132 ('request', 'USB requests', tuple(range(4))),
133 ('errors', 'Errors', (4,)),
136 ('pcap', 'PCAP format'),
143 self.samplerate = None
146 self.transaction_state = 'IDLE'
147 self.ss_transaction = None
148 self.es_transaction = None
149 self.transaction_ep = None
150 self.transaction_addr = None
151 self.wrote_pcap_header = False
153 def putr(self, ss, es, data):
154 self.put(ss, es, self.out_ann, data)
156 def putb(self, ts, data):
157 self.put(ts, ts, self.out_binary, data)
159 def pcap_global_header(self):
160 # See https://wiki.wireshark.org/Development/LibpcapFileFormat.
161 h = b'\xa1\xb2\xc3\xd4' # Magic, indicate microsecond ts resolution
162 h += b'\x00\x02' # Major version 2
163 h += b'\x00\x04' # Minor version 4
164 h += b'\x00\x00\x00\x00' # Correction vs. UTC, seconds
165 h += b'\x00\x00\x00\x00' # Timestamp accuracy
166 h += b'\xff\xff\xff\xff' # Max packet len
167 # LINKTYPE_USB_LINUX_MMAPPED 220
168 # Linux usbmon format, see Documentation/usb/usbmon.txt.
169 h += b'\x00\x00\x00\xdc' # Link layer
172 def metadata(self, key, value):
173 if key == srd.SRD_CONF_SAMPLERATE:
174 self.samplerate = value
176 self.secs_per_sample = float(1) / float(self.samplerate)
179 self.out_binary = self.register(srd.OUTPUT_BINARY)
180 self.out_ann = self.register(srd.OUTPUT_ANN)
182 def handle_transfer(self):
184 request_end = self.handshake in ('ACK', 'STALL', 'timeout')
185 ep = self.transaction_ep
186 addr = self.transaction_addr
188 # Handle protocol STALLs, condition lasts until next SETUP transfer (8.5.3.4)
189 if self.transaction_type == 'SETUP' and (addr, ep) in self.request:
190 request = self.request[(addr,ep)]
191 if request['type'] in ('SETUP IN', 'SETUP OUT'):
192 request['es'] = self.ss_transaction
193 self.handle_request(0, 1)
195 if not (addr, ep) in self.request:
196 self.request[(addr, ep)] = {'setup_data': [], 'data': [],
197 'type': None, 'ss': self.ss_transaction, 'es': None,
198 'id': self.request_id, 'addr': addr, 'ep': ep}
201 request = self.request[(addr,ep)]
204 request['es'] = self.es_transaction
205 request['handshake'] = self.handshake
207 # BULK or INTERRUPT transfer
208 if request['type'] in (None, 'BULK IN') and self.transaction_type == 'IN':
209 request['type'] = 'BULK IN'
210 request['data'] += self.transaction_data
211 self.handle_request(request_started, request_end)
212 elif request['type'] in (None, 'BULK OUT') and self.transaction_type == 'OUT':
213 request['type'] = 'BULK OUT'
214 if self.handshake == 'ACK':
215 request['data'] += self.transaction_data
216 self.handle_request(request_started, request_end)
218 # CONTROL, SETUP stage
219 elif request['type'] is None and self.transaction_type == 'SETUP':
220 request['setup_data'] = self.transaction_data
221 request['wLength'] = struct.unpack('<H',
222 bytes(self.transaction_data[6:8]))[0]
223 if self.transaction_data[0] & 0x80:
224 request['type'] = 'SETUP IN'
225 self.handle_request(1, 0)
227 request['type'] = 'SETUP OUT'
228 self.handle_request(request['wLength'] == 0, 0)
230 # CONTROL, DATA stage
231 elif request['type'] == 'SETUP IN' and self.transaction_type == 'IN':
232 request['data'] += self.transaction_data
234 elif request['type'] == 'SETUP OUT' and self.transaction_type == 'OUT':
235 if self.handshake == 'ACK':
236 request['data'] += self.transaction_data
237 if request['wLength'] == len(request['data']):
238 self.handle_request(1, 0)
240 # CONTROL, STATUS stage
241 elif request['type'] == 'SETUP IN' and self.transaction_type == 'OUT':
242 self.handle_request(0, request_end)
244 elif request['type'] == 'SETUP OUT' and self.transaction_type == 'IN':
245 self.handle_request(0, request_end)
252 def ts_from_samplenum(self, sample):
253 ts = float(sample) * self.secs_per_sample
254 return (int(ts), int((ts % 1.0) * 1e6))
256 def write_pcap_header(self):
257 if not self.wrote_pcap_header:
258 self.put(0, 0, self.out_binary, [0, self.pcap_global_header()])
259 self.wrote_pcap_header = True
261 def request_summary(self, request):
263 if request['type'] in ('SETUP IN', 'SETUP OUT'):
264 for b in request['setup_data']:
267 for b in request['data']:
269 s += ' ] : %s' % request['handshake']
272 def handle_request(self, request_start, request_end):
273 if request_start != 1 and request_end != 1:
275 self.write_pcap_header()
276 ep = self.transaction_ep
277 addr = self.transaction_addr
278 request = self.request[(addr, ep)]
280 ss, es = request['ss'], request['es']
282 if request_start == 1:
283 # Issue PCAP 'SUBMIT' packet.
284 ts = self.ts_from_samplenum(ss)
285 pkt = pcap_usb_pkt(request, ts, True)
286 self.putb(ss, [0, pkt.record_header()])
287 self.putb(ss, [0, pkt.packet()])
291 summary = self.request_summary(request)
292 if request['type'] == 'SETUP IN':
293 self.putr(ss, es, [0, ['SETUP in: %s' % summary]])
294 elif request['type'] == 'SETUP OUT':
295 self.putr(ss, es, [1, ['SETUP out: %s' % summary]])
296 elif request['type'] == 'BULK IN':
297 self.putr(ss, es, [2, ['BULK in: %s' % summary]])
298 elif request['type'] == 'BULK OUT':
299 self.putr(ss, es, [3, ['BULK out: %s' % summary]])
301 # Issue PCAP 'COMPLETE' packet.
302 ts = self.ts_from_samplenum(es)
303 pkt = pcap_usb_pkt(request, ts, False)
304 self.putb(ss, [0, pkt.record_header()])
305 self.putb(ss, [0, pkt.packet()])
306 del self.request[(addr, ep)]
308 def decode(self, ss, es, data):
309 if not self.samplerate:
310 raise SamplerateError('Cannot decode without samplerate.')
313 # We only care about certain packet types for now.
314 if ptype not in ('PACKET'):
317 pcategory, pname, pinfo = pdata
319 if pcategory == 'TOKEN':
322 if self.transaction_state == 'TOKEN RECEIVED':
323 transaction_timeout = self.es_transaction
324 # Token length is 35 bits, timeout is 16..18 bit times
325 # (USB 2.0 7.1.19.1).
326 transaction_timeout += int((self.es_transaction - self.ss_transaction) / 2)
327 if ss > transaction_timeout:
328 self.es_transaction = transaction_timeout
329 self.handshake = 'timeout'
330 self.handle_transfer()
331 self.transaction_state = 'IDLE'
333 if self.transaction_state != 'IDLE':
334 self.putr(ss, es, [4, ['ERR: received %s token in state %s' %
335 (pname, self.transaction_state)]])
338 sync, pid, addr, ep, crc5 = pinfo
339 self.transaction_data = []
340 self.ss_transaction = ss
341 self.es_transaction = es
342 self.transaction_state = 'TOKEN RECEIVED'
343 self.transaction_ep = ep
344 if ep > 0 and pname == 'IN':
345 self.transaction_ep = ep + 0x80
346 self.transaction_addr = addr
347 self.transaction_type = pname # IN OUT SETUP
349 elif pcategory == 'DATA':
350 if self.transaction_state != 'TOKEN RECEIVED':
351 self.putr(ss, es, [4, ['ERR: received %s token in state %s' %
352 (pname, self.transaction_state)]])
355 self.transaction_data = pinfo[2]
356 self.transaction_state = 'DATA RECEIVED'
358 elif pcategory == 'HANDSHAKE':
359 if self.transaction_state not in ('TOKEN RECEIVED', 'DATA RECEIVED'):
360 self.putr(ss, es, [4, ['ERR: received %s token in state %s' %
361 (pname, self.transaction_state)]])
364 self.handshake = pname
365 self.transaction_state = 'IDLE'
366 self.es_transaction = es
367 self.handle_transfer()
373 self.putr(ss, es, [4, ['ERR: received unhandled %s token in state %s' %
374 (pname, self.transaction_state)]])