license: remove FSF postal address from boiler plate license text
[libsigrokdecode.git] / decoders / usb_power_delivery / pd.py
1 ##
2 ## This file is part of the libsigrokdecode project.
3 ##
4 ## Copyright (C) 2015 Google, Inc
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, see <http://www.gnu.org/licenses/>.
18 ##
19
20 import sigrokdecode as srd
21 import struct
22 import zlib   # for crc32
23
24 # BMC encoding with a 600kHz datarate
25 UI_US = 1000000/600000.0
26
27 # Threshold to discriminate half-1 from 0 in Binary Mark Conding
28 THRESHOLD_US = (UI_US + 2 * UI_US) / 2
29
30 # Control Message type
31 CTRL_TYPES = {
32     0: 'reserved',
33     1: 'GOOD CRC',
34     2: 'GOTO MIN',
35     3: 'ACCEPT',
36     4: 'REJECT',
37     5: 'PING',
38     6: 'PS RDY',
39     7: 'GET SOURCE CAP',
40     8: 'GET SINK CAP',
41     9: 'DR SWAP',
42     10: 'PR SWAP',
43     11: 'VCONN SWAP',
44     12: 'WAIT',
45     13: 'SOFT RESET',
46     14: 'reserved',
47     15: 'reserved'
48 }
49
50 # Data message type
51 DATA_TYPES = {
52     1: 'SOURCE CAP',
53     2: 'REQUEST',
54     3: 'BIST',
55     4: 'SINK CAP',
56     15: 'VDM'
57 }
58
59 # 4b5b encoding of the symbols
60 DEC4B5B = [
61     0x10,   # Error      00000
62     0x10,   # Error      00001
63     0x10,   # Error      00010
64     0x10,   # Error      00011
65     0x10,   # Error      00100
66     0x10,   # Error      00101
67     0x13,   # Sync-3     00110
68     0x14,   # RST-1      00111
69     0x10,   # Error      01000
70     0x01,   # 1 = 0001   01001
71     0x04,   # 4 = 0100   01010
72     0x05,   # 5 = 0101   01011
73     0x10,   # Error      01100
74     0x16,   # EOP        01101
75     0x06,   # 6 = 0110   01110
76     0x07,   # 7 = 0111   01111
77     0x10,   # Error      10000
78     0x12,   # Sync-2     10001
79     0x08,   # 8 = 1000   10010
80     0x09,   # 9 = 1001   10011
81     0x02,   # 2 = 0010   10100
82     0x03,   # 3 = 0011   10101
83     0x0A,   # A = 1010   10110
84     0x0B,   # B = 1011   10111
85     0x11,   # Sync-1     11000
86     0x15,   # RST-2      11001
87     0x0C,   # C = 1100   11010
88     0x0D,   # D = 1101   11011
89     0x0E,   # E = 1110   11100
90     0x0F,   # F = 1111   11101
91     0x00,   # 0 = 0000   11110
92     0x10,   # Error      11111
93 ]
94 SYM_ERR = 0x10
95 SYNC1 = 0x11
96 SYNC2 = 0x12
97 SYNC3 = 0x13
98 RST1 = 0x14
99 RST2 = 0x15
100 EOP = 0x16
101 SYNC_CODES = [SYNC1, SYNC2, SYNC3]
102 HRST_CODES = [RST1, RST1, RST1, RST2]
103
104 START_OF_PACKETS = {
105     (SYNC1, SYNC1, SYNC1, SYNC2): 'SOP',
106     (SYNC1, SYNC1, SYNC3, SYNC3): "SOP'",
107     (SYNC1, SYNC3, SYNC1, SYNC3): 'SOP"',
108     (SYNC1, RST2,  RST2,  SYNC3): "SOP' Debug",
109     (SYNC1, RST2,  SYNC3, SYNC2): 'SOP" Debug',
110     (RST1,  SYNC1, RST1,  SYNC3): 'Cable Reset',
111     (RST1,  RST1,  RST1,   RST2): 'Hard Reset',
112 }
113
114 SYM_NAME = [
115     ['0x0', '0'],
116     ['0x1', '1'],
117     ['0x2', '2'],
118     ['0x3', '3'],
119     ['0x4', '4'],
120     ['0x5', '5'],
121     ['0x6', '6'],
122     ['0x7', '7'],
123     ['0x8', '8'],
124     ['0x9', '9'],
125     ['0xA', 'A'],
126     ['0xB', 'B'],
127     ['0xC', 'C'],
128     ['0xD', 'D'],
129     ['0xE', 'E'],
130     ['0xF', 'F'],
131     ['ERROR', 'X'],
132     ['SYNC-1', 'S1'],
133     ['SYNC-2', 'S2'],
134     ['SYNC-3', 'S3'],
135     ['RST-1', 'R1'],
136     ['RST-2', 'R2'],
137     ['EOP', '#'],
138 ]
139
140 RDO_FLAGS = {
141     (1 << 24): 'no_suspend',
142     (1 << 25): 'comm_cap',
143     (1 << 26): 'cap_mismatch',
144     (1 << 27): 'give_back'
145 }
146 PDO_TYPE = ['', 'BATT:', 'VAR:', '<bad>']
147 PDO_FLAGS = {
148     (1 << 29): 'dual_role_power',
149     (1 << 28): 'suspend',
150     (1 << 27): 'ext',
151     (1 << 26): 'comm_cap',
152     (1 << 25): 'dual_role_data'
153 }
154
155 BIST_MODES = {
156         0: 'Receiver',
157         1: 'Transmit',
158         2: 'Counters',
159         3: 'Carrier 0',
160         4: 'Carrier 1',
161         5: 'Carrier 2',
162         6: 'Carrier 3',
163         7: 'Eye',
164 }
165
166 VDM_CMDS = {
167         1: 'Disc Ident',
168         2: 'Disc SVID',
169         3: 'Disc Mode',
170         4: 'Enter Mode',
171         5: 'Exit Mode',
172         6: 'Attention',
173         # 16..31: SVID Specific Commands
174         # DisplayPort Commands
175         16: 'DP Status',
176         17: 'DP Configure',
177 }
178 VDM_ACK = ['REQ', 'ACK', 'NAK', 'BSY']
179
180 class SamplerateError(Exception):
181     pass
182
183 class Decoder(srd.Decoder):
184     api_version = 3
185     id = 'usb_power_delivery'
186     name = 'USB PD'
187     longname = 'USB Power Delivery'
188     desc = 'USB Power Delivery protocol.'
189     license = 'gplv2+'
190     inputs = ['logic']
191     outputs = ['usb_pd']
192     channels = (
193         {'id': 'cc', 'name': 'CC', 'desc': 'Control channel'},
194     )
195     options = (
196         {'id': 'fulltext', 'desc': 'full text decoding of the packet',
197          'default': 'no', 'values': ('yes', 'no')},
198     )
199     annotations = (
200         ('type', 'Packet Type'),
201         ('Preamble', 'Preamble'),
202         ('SOP', 'Start of Packet'),
203         ('Head', 'Header'),
204         ('Data', 'Data'),
205         ('CRC', 'Checksum'),
206         ('EOP', 'End Of Packet'),
207         ('Sym', '4b5b symbols'),
208         ('warnings', 'Warnings'),
209         ('src', 'Source Message'),
210         ('snk', 'Sink Message'),
211         ('payload', 'Payload'),
212         ('text', 'Plain text'),
213     )
214     annotation_rows = (
215        ('4B5B', 'symbols', (7, )),
216        ('Phase', 'parts', (1, 2, 3, 4, 5, 6, )),
217        ('payload', 'Payload', (11, )),
218        ('type', 'Type', (0, 9, 10, )),
219        ('warnings', 'Warnings', (8, )),
220        ('text', 'Full text', (12, )),
221     )
222     binary = (
223         ('raw-data', 'RAW binary data'),
224     )
225
226     def get_request(self, rdo):
227         pos = (rdo >> 28) & 7
228         op_ma = ((rdo >> 10) & 0x3ff) * 10
229         max_ma = (rdo & 0x3ff) * 10
230         flags = ''
231         for f in RDO_FLAGS.keys():
232             if rdo & f:
233                 flags += ' ' + RDO_FLAGS[f]
234         return '[%d]%d/%d mA%s' % (pos, op_ma, max_ma, flags)
235
236     def get_source_cap(self, pdo):
237         t = (pdo >> 30) & 3
238         if t == 0:
239             mv = ((pdo >> 10) & 0x3ff) * 50
240             ma = ((pdo >> 0) & 0x3ff) * 10
241             p = '%.1fV %.1fA' % (mv/1000.0, ma/1000.0)
242         elif t == 1:
243             minv = ((pdo >> 10) & 0x3ff) * 50
244             maxv = ((pdo >> 20) & 0x3ff) * 50
245             mw = ((pdo >> 0) & 0x3ff) * 250
246             p = '%.1f/%.1fV %.1fW' % (minv/1000.0, maxv/1000.0, mw/1000.0)
247         elif t == 2:
248             minv = ((pdo >> 10) & 0x3ff) * 50
249             maxv = ((pdo >> 20) & 0x3ff) * 50
250             ma = ((pdo >> 0) & 0x3ff) * 10
251             p = '%.1f/%.1fV %.1fA' % (minv/1000.0, maxv/1000.0, ma/1000.0)
252         else:
253             p = ''
254         flags = ''
255         for f in PDO_FLAGS.keys():
256             if pdo & f:
257                 flags += ' ' + PDO_FLAGS[f]
258         return '%s%s%s' % (PDO_TYPE[t], p, flags)
259
260     def get_sink_cap(self, pdo):
261         t = (pdo >> 30) & 3
262         if t == 0:
263             mv = ((pdo >> 10) & 0x3ff) * 50
264             ma = ((pdo >> 0) & 0x3ff) * 10
265             p = '%.1fV %.1fA' % (mv/1000.0, ma/1000.0)
266         elif t == 1:
267             minv = ((pdo >> 10) & 0x3ff) * 50
268             maxv = ((pdo >> 20) & 0x3ff) * 50
269             mw = ((pdo >> 0) & 0x3ff) * 250
270             p = '%.1f/%.1fV %.1fW' % (minv/1000.0, maxv/1000.0, mw/1000.0)
271         elif t == 2:
272             minv = ((pdo >> 10) & 0x3ff) * 50
273             maxv = ((pdo >> 20) & 0x3ff) * 50
274             ma = ((pdo >> 0) & 0x3ff) * 10
275             p = '%.1f/%.1fV %.1fA' % (minv/1000.0, maxv/1000.0, ma/1000.0)
276         else:
277             p = ''
278         flags = ''
279         for f in PDO_FLAGS.keys():
280             if pdo & f:
281                 flags += ' ' + PDO_FLAGS[f]
282         return '%s%s%s' % (PDO_TYPE[t], p, flags)
283
284     def get_vdm(self, idx, data):
285         if idx == 0:    # VDM header
286             vid = data >> 16
287             struct = data & (1 << 15)
288             txt = 'VDM'
289             if struct:  # Structured VDM
290                 cmd = data & 0x1f
291                 src = data & (1 << 5)
292                 ack = (data >> 6) & 3
293                 pos = (data >> 8) & 7
294                 ver = (data >> 13) & 3
295                 txt = VDM_ACK[ack] + ' '
296                 txt += VDM_CMDS[cmd] if cmd in VDM_CMDS else 'cmd?'
297                 txt += ' pos %d' % (pos) if pos else ' '
298             else:   # Unstructured VDM
299                 txt = 'unstruct [%04x]' % (data & 0x7fff)
300             txt += ' SVID:%04x' % (vid)
301         else:   # VDM payload
302             txt = 'VDO:%08x' % (data)
303         return txt
304
305     def get_bist(self, idx, data):
306         mode = data >> 28
307         counter = data & 0xffff
308         mode_name = BIST_MODES[mode] if mode in BIST_MODES else 'INVALID'
309         if mode == 2:
310             mode_name = 'Counter[= %d]' % (counter)
311         # TODO check all 0 bits are 0 / emit warnings
312         return 'mode %s' % (mode_name) if idx == 0 else 'invalid BRO'
313
314     def putpayload(self, s0, s1, idx):
315         t = self.head_type()
316         txt = '???'
317         if t == 2:
318             txt = self.get_request(self.data[idx])
319         elif t == 1:
320             txt = self.get_source_cap(self.data[idx])
321         elif t == 4:
322             txt = self.get_sink_cap(self.data[idx])
323         elif t == 15:
324             txt = self.get_vdm(idx, self.data[idx])
325         elif t == 3:
326             txt = self.get_bist(idx, self.data[idx])
327         self.putx(s0, s1, [11, [txt, txt]])
328         self.text += ' - ' + txt
329
330     def puthead(self):
331         ann_type = 9 if self.head_power_role() else 10
332         role = 'SRC' if self.head_power_role() else 'SNK'
333         if self.head_data_role() != self.head_power_role():
334             role += '/DFP' if self.head_data_role() else '/UFP'
335         t = self.head_type()
336         if self.head_count() == 0:
337             shortm = CTRL_TYPES[t]
338         else:
339             shortm = DATA_TYPES[t] if t in DATA_TYPES else 'DAT???'
340
341         longm = '{:s}[{:d}]:{:s}'.format(role, self.head_id(), shortm)
342         self.putx(0, -1, [ann_type, [longm, shortm]])
343         self.text += longm
344
345     def head_id(self):
346         return (self.head >> 9) & 7
347
348     def head_power_role(self):
349         return (self.head >> 8) & 1
350
351     def head_data_role(self):
352         return (self.head >> 5) & 1
353
354     def head_rev(self):
355         return ((self.head >> 6) & 3) + 1
356
357     def head_type(self):
358         return self.head & 0xF
359
360     def head_count(self):
361         return (self.head >> 12) & 7
362
363     def putx(self, s0, s1, data):
364         self.put(self.edges[s0], self.edges[s1], self.out_ann, data)
365
366     def putwarn(self, longm, shortm):
367         self.putx(0, -1, [8, [longm, shortm]])
368
369     def compute_crc32(self):
370         bdata = struct.pack('<H'+'I'*len(self.data), self.head & 0xffff,
371                             *tuple([d & 0xffffffff for d in self.data]))
372         return zlib.crc32(bdata)
373
374     def rec_sym(self, i, sym):
375         self.putx(i, i+5, [7, SYM_NAME[sym]])
376
377     def get_sym(self, i, rec=True):
378         v = (self.bits[i] | (self.bits[i+1] << 1) | (self.bits[i+2] << 2) |
379              (self.bits[i+3] << 3) | (self.bits[i+4] << 4))
380         sym = DEC4B5B[v]
381         if rec:
382             self.rec_sym(i, sym)
383         return sym
384
385     def get_short(self):
386         i = self.idx
387         # Check it's not a truncated packet
388         if len(self.bits) - i <= 20:
389             self.putwarn('Truncated', '!')
390             return 0x0BAD
391         k = [self.get_sym(i), self.get_sym(i+5),
392              self.get_sym(i+10), self.get_sym(i+15)]
393         # TODO check bad symbols
394         val = k[0] | (k[1] << 4) | (k[2] << 8) | (k[3] << 12)
395         self.idx += 20
396         return val
397
398     def get_word(self):
399         lo = self.get_short()
400         hi = self.get_short()
401         return lo | (hi << 16)
402
403     def find_corrupted_sop(self, k):
404         # Start of packet are valid even if they have only 3 correct symbols
405         # out of 4.
406         for seq in START_OF_PACKETS.keys():
407             if [k[i] == seq[i] for i in range(len(k))].count(True) >= 3:
408                 return START_OF_PACKETS[seq]
409         return None
410
411     def scan_eop(self):
412         for i in range(len(self.bits) - 19):
413             k = (self.get_sym(i, rec=False), self.get_sym(i+5, rec=False),
414                  self.get_sym(i+10, rec=False), self.get_sym(i+15, rec=False))
415             sym = START_OF_PACKETS[k] if k in START_OF_PACKETS else None
416             if not sym:
417                 sym = self.find_corrupted_sop(k)
418             # We have an interesting symbol sequence
419             if sym:
420                 # annotate the preamble
421                 self.putx(0, i, [1, ['Preamble', '...']])
422                 # annotate each symbol
423                 self.rec_sym(i, k[0])
424                 self.rec_sym(i+5, k[1])
425                 self.rec_sym(i+10, k[2])
426                 self.rec_sym(i+15, k[3])
427                 if sym == 'Hard Reset':
428                     self.text += 'HRST'
429                     return -1   # Hard reset
430                 elif sym == 'Cable Reset':
431                     self.text += 'CRST'
432                     return -1   # Cable reset
433                 else:
434                     self.putx(i, i+20, [2, [sym, 'S']])
435                 return i+20
436         self.putx(0, len(self.bits), [1, ['Junk???', 'XXX']])
437         self.text += 'Junk???'
438         self.putwarn('No start of packet found', 'XXX')
439         return -1   # No Start Of Packet
440
441     def __init__(self):
442         self.samplerate = None
443         self.idx = 0
444         self.packet_seq = 0
445         self.previous = 0
446         self.startsample = None
447         self.bits = []
448         self.edges = []
449         self.bad = []
450         self.half_one = False
451         self.start_one = 0
452
453     def metadata(self, key, value):
454         if key == srd.SRD_CONF_SAMPLERATE:
455             self.samplerate = value
456             # 0 is 2 UI, space larger than 1.5x 0 is definitely wrong
457             self.maxbit = self.us2samples(3 * UI_US)
458             # duration threshold between half 1 and 0
459             self.threshold = self.us2samples(THRESHOLD_US)
460
461     def start(self):
462         self.out_python = self.register(srd.OUTPUT_PYTHON)
463         self.out_ann = self.register(srd.OUTPUT_ANN)
464         self.out_binary = self.register(srd.OUTPUT_BINARY)
465         self.out_bitrate = self.register(
466             srd.OUTPUT_META,
467             meta=(int, 'Bitrate', 'Bitrate during the packet')
468         )
469
470     def us2samples(self, us):
471         return int(us * self.samplerate / 1000000)
472
473     def decode_packet(self):
474         self.data = []
475         self.idx = 0
476         self.text = ''
477
478         if len(self.edges) < 50:
479             return  # Not a real PD packet
480
481         self.packet_seq += 1
482         tstamp = float(self.startsample) / self.samplerate
483         self.text += '#%-4d (%8.6fms): ' % (self.packet_seq, tstamp*1000)
484
485         self.idx = self.scan_eop()
486         if self.idx < 0:
487             # Full text trace of the issue
488             self.putx(0, self.idx, [12, [self.text, '...']])
489             return  # No real packet: ABORT
490
491         # Packet header
492         self.head = self.get_short()
493         self.putx(self.idx-20, self.idx, [3, ['H:%04x' % (self.head), 'HD']])
494         self.puthead()
495
496         # Decode data payload
497         for i in range(self.head_count()):
498             self.data.append(self.get_word())
499             self.putx(self.idx-40, self.idx,
500                       [4, ['[%d]%08x' % (i, self.data[i]), 'D%d' % (i)]])
501             self.putpayload(self.idx-40, self.idx, i)
502
503         # CRC check
504         self.crc = self.get_word()
505         ccrc = self.compute_crc32()
506         if self.crc != ccrc:
507             self.putwarn('Bad CRC %08x != %08x' % (self.crc, ccrc), 'CRC!')
508         self.putx(self.idx-40, self.idx, [5, ['CRC:%08x' % (self.crc), 'CRC']])
509
510         # End of Packet
511         if len(self.bits) >= self.idx + 5 and self.get_sym(self.idx) == EOP:
512             self.putx(self.idx, self.idx + 5, [6, ['EOP', 'E']])
513             self.idx += 5
514         else:
515             self.putwarn('No EOP', 'EOP!')
516         # Full text trace
517         if self.options['fulltext'] == 'yes':
518             self.putx(0, self.idx, [12, [self.text, '...']])
519
520         # Meta data for bitrate
521         ss, es = self.edges[0], self.edges[-1]
522         bitrate = self.samplerate*len(self.bits) / float(es - ss)
523         self.put(es, ss, self.out_bitrate, int(bitrate))
524         # Raw binary data (BMC decoded)
525         self.put(es, ss, self.out_binary, [0, bytes(self.bits)])
526
527     def decode(self):
528         if not self.samplerate:
529             raise SamplerateError('Cannot decode without samplerate.')
530         while True:
531             self.wait({0: 'e'})
532
533             # First sample of the packet, just record the start date
534             if not self.startsample:
535                 self.startsample = self.samplenum
536                 self.previous = self.samplenum
537                 continue
538
539             diff = self.samplenum - self.previous
540
541             # Large idle: use it as the end of packet
542             if diff > self.maxbit:
543                 # the last edge of the packet
544                 self.edges.append(self.previous)
545                 # Export the packet
546                 self.decode_packet()
547                 # Reset for next packet
548                 self.startsample = self.samplenum
549                 self.bits = []
550                 self.edges = []
551                 self.bad = []
552                 self.half_one = False
553                 self.start_one = 0
554             else:   # add the bit to the packet
555                 is_zero = diff > self.threshold
556                 if is_zero and not self.half_one:
557                     self.bits.append(0)
558                     self.edges.append(self.previous)
559                 elif not is_zero and self.half_one:
560                     self.bits.append(1)
561                     self.edges.append(self.start_one)
562                     self.half_one = False
563                 elif not is_zero and not self.half_one:
564                     self.half_one = True
565                     self.start_one = self.previous
566                 else:   # Invalid BMC sequence
567                     self.bad.append((self.start_one, self.previous))
568                     # TODO try to recover
569                     self.bits.append(0)
570                     self.edges.append(self.previous)
571                     self.half_one = False
572             self.previous = self.samplenum