Use consistent __init__() format across all PDs.
[libsigrokdecode.git] / decoders / swd / pd.py
1 ##
2 ## This file is part of the libsigrokdecode project.
3 ##
4 ## Copyright (C) 2014 Angus Gratton <gus@projectgus.com>
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 re
23
24 '''
25 OUTPUT_PYTHON format:
26
27 Packet:
28 [<ptype>, <pdata>]
29
30 <ptype>:
31  - 'AP_READ' (AP read)
32  - 'DP_READ' (DP read)
33  - 'AP_WRITE' (AP write)
34  - 'DP_WRITE' (DP write)
35  - 'LINE_RESET' (line reset sequence)
36
37 <pdata>:
38   - tuple of address, ack state, data for the given sequence
39 '''
40
41 swd_states = [
42     'IDLE', # Idle/unknown
43     'REQUEST', # Request phase (first 8 bits)
44     'ACK', # Ack phase (next 3 bits)
45     'READ', # Reading phase (next 32 bits for reads)
46     'WRITE', # Writing phase (next 32 bits for write)
47     'DPARITY', # Data parity phase
48 ]
49
50 # Regexes for matching SWD data out of bitstring ('1' / '0' characters) format
51 RE_SWDSWITCH = re.compile(bin(0xE79E)[:1:-1] + '$')
52 RE_SWDREQ = re.compile(r'1(?P<apdp>.)(?P<rw>.)(?P<addr>..)(?P<parity>.)01$')
53 RE_IDLE = re.compile('0' * 50 + '$')
54
55 # Sample edges
56 RISING = 1
57 FALLING = 0
58
59 ADDR_DP_SELECT = 0x8
60 ADDR_DP_CTRLSTAT = 0x4
61
62 BIT_SELECT_CTRLSEL = 1
63 BIT_CTRLSTAT_ORUNDETECT = 1
64
65 ANNOTATIONS = ['reset', 'enable', 'read', 'write', 'ack', 'data', 'parity']
66
67 class Decoder(srd.Decoder):
68     api_version = 2
69     id = 'swd'
70     name = 'SWD'
71     longname = 'Serial Wire Debug'
72     desc = 'Two-wire protocol for debug access to ARM CPUs.'
73     license = 'gplv2+'
74     inputs = ['logic']
75     outputs = ['swd']
76     channels = (
77         {'id': 'swclk', 'name': 'SWCLK', 'desc': 'Master clock'},
78         {'id': 'swdio', 'name': 'SWDIO', 'desc': 'Data input/output'},
79     )
80     options = (
81         {'id': 'strict_start',
82          'desc': 'Wait for a line reset before starting to decode',
83          'default': 'no', 'values': ('yes', 'no')},
84     )
85     annotations = (
86         ('reset', 'RESET'),
87         ('enable', 'ENABLE'),
88         ('read', 'READ'),
89         ('write', 'WRITE'),
90         ('ack', 'ACK'),
91         ('data', 'DATA'),
92         ('parity', 'PARITY'),
93     )
94
95     def __init__(self):
96         # SWD data/clock state
97         self.state = 'UNKNOWN'
98         self.oldclk = -1
99         self.sample_edge = RISING
100         self.ack = None # Ack state of the current phase
101         self.ss_req = 0 # Start sample of current req
102         self.turnaround = 0 # Number of turnaround edges to ignore before continuing
103         self.bits = '' # Bits from SWDIO are accumulated here, matched against expected sequences
104         self.samplenums = [] # Sample numbers that correspond to the samples in self.bits
105         self.linereset_count = 0
106
107         # SWD debug port state
108         self.data = None
109         self.addr = None
110         self.rw = None # Are we inside an SWD read or a write?
111         self.ctrlsel = 0 # 'ctrlsel' is bit 0 in the SELECT register.
112         self.orundetect = 0 # 'orundetect' is bit 0 in the CTRLSTAT register.
113
114     def start(self):
115         self.out_ann = self.register(srd.OUTPUT_ANN)
116         self.out_python = self.register(srd.OUTPUT_PYTHON)
117         if self.options['strict_start'] == 'no':
118             self.state = 'REQ' # No need to wait for a LINE RESET.
119
120     def putx(self, ann, length, data):
121         '''Output annotated data.'''
122         ann = ANNOTATIONS.index(ann)
123         try:
124             ss = self.samplenums[-length]
125         except IndexError:
126             ss = self.samplenums[0]
127         if self.state == 'REQ':
128             self.ss_req = ss
129         es = self.samplenum
130         self.put(ss, es, self.out_ann, [ann, [data]])
131
132     def putp(self, ptype, pdata):
133         self.put(self.ss_req, self.samplenum, self.out_python, [ptype, pdata])
134
135     def put_python_data(self):
136         '''Emit Python data item based on current SWD packet contents.'''
137         ptype = {
138             ('AP', 'R'): 'AP_READ',
139             ('AP', 'W'): 'AP_WRITE',
140             ('DP', 'R'): 'DP_READ',
141             ('DP', 'W'): 'DP_WRITE',
142         }[(self.apdp, self.rw)]
143         self.putp(ptype, (self.addr, self.data, self.ack))
144
145     def decode(self, ss, es, data):
146         for (self.samplenum, (clk, dio)) in data:
147             if clk == self.oldclk:
148                 continue # Not a clock edge.
149             self.oldclk = clk
150
151             # Count rising edges with DIO held high,
152             # as a line reset (50+ high edges) can happen from any state.
153             if clk == RISING:
154                 if dio == 1:
155                     self.linereset_count += 1
156                 else:
157                     if self.linereset_count >= 50:
158                         self.putx('reset', self.linereset_count, 'LINERESET')
159                         self.putp('LINE_RESET', None)
160                         self.reset_state()
161                     self.linereset_count = 0
162
163             # Otherwise, we only care about either rising or falling edges
164             # (depending on sample_edge, set according to current state).
165             if clk != self.sample_edge:
166                 continue
167
168             # Turnaround bits get skipped.
169             if self.turnaround > 0:
170                 self.turnaround -= 1
171                 continue
172
173             self.bits += str(dio)
174             self.samplenums.append(self.samplenum)
175             {
176                 'UNKNOWN': self.handle_unknown_edge,
177                 'REQ': self.handle_req_edge,
178                 'ACK': self.handle_ack_edge,
179                 'DATA': self.handle_data_edge,
180                 'DPARITY': self.handle_dparity_edge,
181             }[self.state]()
182
183     def next_state(self):
184         '''Step to the next SWD state, reset internal counters accordingly.'''
185         self.bits = ''
186         self.samplenums = []
187         self.linereset_count = 0
188         if self.state == 'UNKNOWN':
189             self.state = 'REQ'
190             self.sample_edge = RISING
191             self.turnaround = 0
192         elif self.state == 'REQ':
193             self.state = 'ACK'
194             self.sample_edge = FALLING
195             self.turnaround = 1
196         elif self.state == 'ACK':
197             self.state = 'DATA'
198             self.sample_edge = RISING if self.rw == 'W' else FALLING
199             self.turnaround = 0 if self.rw == 'R' else 2
200         elif self.state == 'DATA':
201             self.state = 'DPARITY'
202         elif self.state == 'DPARITY':
203             self.put_python_data()
204             self.state = 'REQ'
205             self.sample_edge = RISING
206             self.turnaround = 1 if self.rw == 'R' else 0
207
208     def reset_state(self):
209         '''Line reset (or equivalent), wait for a new pending SWD request.'''
210         if self.state != 'REQ': # Emit a Python data item.
211             self.put_python_data()
212         # Clear state.
213         self.bits = ''
214         self.samplenums = []
215         self.linereset_count = 0
216         self.turnaround = 0
217         self.sample_edge = RISING
218         self.data = ''
219         self.ack = None
220         self.state = 'REQ'
221
222     def handle_unknown_edge(self):
223         '''
224         Clock edge in the UNKNOWN state.
225         In the unknown state, clock edges get ignored until we see a line
226         reset (which is detected in the decode method, not here.)
227         '''
228         pass
229
230     def handle_req_edge(self):
231         '''Clock edge in the REQ state (waiting for SWD r/w request).'''
232         # Check for a JTAG->SWD enable sequence.
233         m = re.search(RE_SWDSWITCH, self.bits)
234         if m is not None:
235             self.putx('enable', 16, 'JTAG->SWD')
236             self.reset_state()
237             return
238
239         # Or a valid SWD Request packet.
240         m = re.search(RE_SWDREQ, self.bits)
241         if m is not None:
242             calc_parity = sum([int(x) for x in m.group('rw') + m.group('apdp') + m.group('addr')]) % 2
243             parity = '' if str(calc_parity) == m.group('parity') else 'E'
244             self.rw = 'R' if m.group('rw') == '1' else 'W'
245             self.apdp = 'AP' if m.group('apdp') == '1' else 'DP'
246             self.addr = int(m.group('addr')[::-1], 2) << 2
247             self.putx('read' if self.rw == 'R' else 'write', 8, self.get_address_description())
248             self.next_state()
249             return
250
251     def handle_ack_edge(self):
252         '''Clock edge in the ACK state (waiting for complete ACK sequence).'''
253         if len(self.bits) < 3:
254             return
255         if self.bits == '100':
256             self.putx('ack', 3, 'OK')
257             self.ack = 'OK'
258             self.next_state()
259         elif self.bits == '001':
260             self.putx('ack', 3, 'FAULT')
261             self.ack = 'FAULT'
262             if self.orundetect == 1:
263                 self.next_state()
264             else:
265                 self.reset_state()
266             self.turnaround = 1
267         elif self.bits == '010':
268             self.putx('ack', 3, 'WAIT')
269             self.ack = 'WAIT'
270             if self.orundetect == 1:
271                 self.next_state()
272             else:
273                 self.reset_state()
274             self.turnaround = 1
275         elif self.bits == '111':
276             self.putx('ack', 3, 'NOREPLY')
277             self.ack = 'NOREPLY'
278             self.reset_state()
279         else:
280             self.putx('ack', 3, 'ERROR')
281             self.ack = 'ERROR'
282             self.reset_state()
283
284     def handle_data_edge(self):
285         '''Clock edge in the DATA state (waiting for 32 bits to clock past).'''
286         if len(self.bits) < 32:
287             return
288         self.data = 0
289         self.dparity = 0
290         for x in range(32):
291             if self.bits[x] == '1':
292                 self.data += (1 << x)
293                 self.dparity += 1
294         self.dparity = self.dparity % 2
295
296         self.putx('data', 32, '0x%08x' % self.data)
297         self.next_state()
298
299     def handle_dparity_edge(self):
300         '''Clock edge in the DPARITY state (clocking in parity bit).'''
301         if str(self.dparity) != self.bits:
302             self.putx('parity', 1, str(self.dparity) + self.bits) # PARITY ERROR
303         elif self.rw == 'W':
304             self.handle_completed_write()
305         self.next_state()
306
307     def handle_completed_write(self):
308         '''
309         Update internal state of the debug port based on a completed
310         write operation.
311         '''
312         if self.apdp != 'DP':
313             return
314         elif self.addr == ADDR_DP_SELECT:
315             self.ctrlsel = self.data & BIT_SELECT_CTRLSEL
316         elif self.addr == ADDR_DP_CTRLSTAT and self.ctrlsel == 0:
317             self.orundetect = self.data & BIT_CTRLSTAT_ORUNDETECT
318
319     def get_address_description(self):
320         '''
321         Return a human-readable description of the currently selected address,
322         for annotated results.
323         '''
324         if self.apdp == 'DP':
325             if self.rw == 'R':
326                 # Tables 2-4 & 2-5 in ADIv5.2 spec ARM document IHI 0031C
327                 return {
328                     0: 'IDCODE',
329                     0x4: 'R CTRL/STAT' if self.ctrlsel == 0 else 'R DLCR',
330                     0x8: 'RESEND',
331                     0xC: 'RDBUFF'
332                 }[self.addr]
333             elif self.rw == 'W':
334                 # Tables 2-4 & 2-5 in ADIv5.2 spec ARM document IHI 0031C
335                 return {
336                     0: 'W ABORT',
337                     0x4: 'W CTRL/STAT' if self.ctrlsel == 0 else 'W DLCR',
338                     0x8: 'W SELECT',
339                     0xC: 'W RESERVED'
340                 }[self.addr]
341         elif self.apdp == 'AP':
342             if self.rw == 'R':
343                 return 'R AP%x' % self.addr
344             elif self.rw == 'W':
345                 return 'W AP%x' % self.addr
346
347         # Any legitimate operations shouldn't fall through to here, probably
348         # a decoder bug.
349         return '? %s%s%x' % (self.rw, self.apdp, self.addr)