7a156ffe6865b451d9df7c6f99b7eece636eaa38
[libsigrokdecode.git] / decoders / usb_request / __init__.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 '''
22 This decoder stacks on top of the 'usb_packet' PD and decodes the USB
23 (low-speed and full-speed) transactions.
24
25 Transactions and requests are tracked per device address and endpoint.
26
27 Tracking of CONTROL requests is quite accurate, as these always start with
28 a SETUP token and are completed by an IN or OUT transaction, the status
29 packet. All transactions during the DATA stage are combined.
30
31 For BULK and INTERRUPT requests, each transaction starts with an IN or OUT
32 request, and is considered completed after the first transaction containing
33 data has been ACKed. Normally a request is only completed after a short or
34 zero length packet, but this would require knowledge about the max packet
35 size of an endpoint.
36
37 All INTERRUPT requests are treated as BULK requests, as on the link layer
38 both are identical.
39
40 The PCAP binary output contains 'SUBMIT' and 'COMPLETE' records. For
41 CONTROL request, the SUBMIT contains the SETUP request, the data is
42 either contained in the SUBMIT (Host-to-Device) or the COMPLETE
43 (Device-to-Host) record.
44
45 Details:
46 https://en.wikipedia.org/wiki/USB
47 http://www.usb.org/developers/docs/
48 '''
49
50 from .pd import Decoder