license: remove FSF postal address from boiler plate license text
[libsigrokdecode.git] / decoders / eeprom24xx / pd.py
1 ##
2 ## This file is part of the libsigrokdecode project.
3 ##
4 ## Copyright (C) 2014 Uwe Hermann <uwe@hermann-uwe.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, see <http://www.gnu.org/licenses/>.
18 ##
19
20 import sigrokdecode as srd
21 from .lists import *
22
23 class Decoder(srd.Decoder):
24     api_version = 2
25     id = 'eeprom24xx'
26     name = '24xx EEPROM'
27     longname = '24xx I²C EEPROM'
28     desc = '24xx series I²C EEPROM protocol.'
29     license = 'gplv2+'
30     inputs = ['i2c']
31     outputs = ['eeprom24xx']
32     options = (
33         {'id': 'chip', 'desc': 'Chip', 'default': 'generic',
34             'values': tuple(chips.keys())},
35         {'id': 'addr_counter', 'desc': 'Initial address counter value',
36             'default': 0},
37     )
38     annotations = (
39         # Warnings
40         ('warnings', 'Warnings'),
41         # Bits/bytes
42         ('control-code', 'Control code'),
43         ('address-pin', 'Address pin (A0/A1/A2)'),
44         ('rw-bit', 'Read/write bit'),
45         ('word-addr-byte', 'Word address byte'),
46         ('data-byte', 'Data byte'),
47         # Fields
48         ('control-word', 'Control word'),
49         ('word-addr', 'Word address'),
50         ('data', 'Data'),
51         # Operations
52         ('byte-write', 'Byte write'),
53         ('page-write', 'Page write'),
54         ('cur-addr-read', 'Current address read'),
55         ('random-read', 'Random read'),
56         ('seq-random-read', 'Sequential random read'),
57         ('seq-cur-addr-read', 'Sequential current address read'),
58         ('ack-polling', 'Acknowledge polling'),
59         ('set-bank-addr', 'Set bank address'), # SBA. Only 34AA04.
60         ('read-bank-addr', 'Read bank address'), # RBA. Only 34AA04.
61         ('set-wp', 'Set write protection'), # SWP
62         ('clear-all-wp', 'Clear all write protection'), # CWP
63         ('read-wp', 'Read write protection status'), # RPS
64     )
65     annotation_rows = (
66         ('bits-bytes', 'Bits/bytes', (1, 2, 3, 4, 5)),
67         ('fields', 'Fields', (6, 7, 8)),
68         ('ops', 'Operations', tuple(range(9, 21))),
69         ('warnings', 'Warnings', (0,)),
70     )
71     binary = (
72         ('binary', 'Binary'),
73     )
74
75     def __init__(self):
76         self.reset()
77
78     def start(self):
79         self.out_ann = self.register(srd.OUTPUT_ANN)
80         self.out_binary = self.register(srd.OUTPUT_BINARY)
81         self.chip = chips[self.options['chip']]
82         self.addr_counter = self.options['addr_counter']
83
84     def putb(self, data):
85         self.put(self.ss_block, self.es_block, self.out_ann, data)
86
87     def putbin(self, data):
88         self.put(self.ss_block, self.es_block, self.out_binary, data)
89
90     def putbits(self, bit1, bit2, bits, data):
91         self.put(bits[bit1][1], bits[bit2][2], self.out_ann, data)
92
93     def reset(self):
94         self.state = 'WAIT FOR START'
95         self.packets = []
96         self.bytebuf = []
97         self.is_cur_addr_read = False
98         self.is_random_access_read = False
99         self.is_seq_random_read = False
100         self.is_byte_write = False
101         self.is_page_write = False
102
103     def packet_append(self):
104         self.packets.append([self.ss, self.es, self.cmd, self.databyte, self.bits])
105         if self.cmd in ('DATA READ', 'DATA WRITE'):
106             self.bytebuf.append(self.databyte)
107
108     def hexbytes(self, idx):
109         return ' '.join(['%02X' % b for b in self.bytebuf[idx:]])
110
111     def put_control_word(self, bits):
112         s = ''.join(['%d' % b[0] for b in reversed(bits[4:])])
113         self.putbits(7, 4, bits, [1, ['Control code bits: ' + s,
114             'Control code: ' + s, 'Ctrl code: ' + s, 'Ctrl code', 'Ctrl', 'C']])
115         for i in reversed(range(self.chip['addr_pins'])):
116             self.putbits(i + 1, i + 1, bits,
117                 [2, ['Address bit %d: %d' % (i, bits[i + 1][0]),
118                      'Addr bit %d' % i, 'A%d' % i, 'A']])
119         s1 = 'read' if bits[0][0] == 1 else 'write'
120         s2 = 'R' if bits[0][0] == 1 else 'W'
121         self.putbits(0, 0, bits, [3, ['R/W bit: ' + s1, 'R/W', 'RW', s2]])
122         self.putbits(7, 0, bits, [6, ['Control word', 'Control', 'CW', 'C']])
123
124     def put_word_addr(self, p):
125         if self.chip['addr_bytes'] == 1:
126             a = p[1][3]
127             self.put(p[1][0], p[1][1], self.out_ann,
128                 [4, ['Word address byte: %02X' % a, 'Word addr byte: %02X' % a,
129                      'Addr: %02X' % a, 'A: %02X' % a, '%02X' % a]])
130             self.put(p[1][0], p[1][1], self.out_ann, [7, ['Word address',
131                      'Word addr', 'Addr', 'A']])
132             self.addr_counter = a
133         else:
134             a = p[1][3]
135             self.put(p[1][0], p[1][1], self.out_ann,
136                 [4, ['Word address high byte: %02X' % a,
137                      'Word addr high byte: %02X' % a,
138                      'Addr high: %02X' % a, 'AH: %02X' % a, '%02X' % a]])
139             a = p[2][3]
140             self.put(p[2][0], p[2][1], self.out_ann,
141                 [4, ['Word address low byte: %02X' % a,
142                      'Word addr low byte: %02X' % a,
143                      'Addr low: %02X' % a, 'AL: %02X' % a, '%02X' % a]])
144             self.put(p[1][0], p[2][1], self.out_ann, [7, ['Word address',
145                      'Word addr', 'Addr', 'A']])
146             self.addr_counter = (p[1][3] << 8) | p[2][3]
147
148     def put_data_byte(self, p):
149         if self.chip['addr_bytes'] == 1:
150             s = '%02X' % self.addr_counter
151         else:
152             s = '%04X' % self.addr_counter
153         self.put(p[0], p[1], self.out_ann, [5, ['Data byte %s: %02X' % \
154             (s, p[3]), 'Data byte: %02X' % p[3], \
155             'Byte: %02X' % p[3], 'DB: %02X' % p[3], '%02X' % p[3]]])
156
157     def put_data_bytes(self, idx, cls, s):
158         for p in self.packets[idx:]:
159             self.put_data_byte(p)
160             self.addr_counter += 1
161         self.put(self.packets[idx][0], self.packets[-1][1], self.out_ann,
162             [8, ['Data', 'D']])
163         a = ''.join(['%s' % c[0] for c in s.split()]).upper()
164         self.putb([cls, ['%s (%s): %s' % (s, self.addr_and_len(), \
165                   self.hexbytes(self.chip['addr_bytes'])),
166                   '%s (%s)' % (s, self.addr_and_len()), s, a, s[0]]])
167         self.putbin([0, bytes(self.bytebuf[self.chip['addr_bytes']:])])
168
169     def addr_and_len(self):
170         if self.chip['addr_bytes'] == 1:
171             a = '%02X' % self.bytebuf[0]
172         else:
173             a = '%02X%02X' % tuple(self.bytebuf[:2])
174         num_data_bytes = len(self.bytebuf) - self.chip['addr_bytes']
175         d = '%d bytes' % num_data_bytes
176         if num_data_bytes <= 1:
177             d = d[:-1]
178         return 'addr=%s, %s' % (a, d)
179
180     def decide_on_seq_or_rnd_read(self):
181         if len(self.bytebuf) < 2:
182             self.reset()
183             return
184         if len(self.bytebuf) == 2:
185             self.is_random_access_read = True
186         else:
187             self.is_seq_random_read = True
188
189     def put_operation(self):
190         idx = 1 + self.chip['addr_bytes']
191         if self.is_byte_write:
192             # Byte write: word address, one data byte.
193             self.put_word_addr(self.packets)
194             self.put_data_bytes(idx, 9, 'Byte write')
195         elif self.is_page_write:
196             # Page write: word address, two or more data bytes.
197             self.put_word_addr(self.packets)
198             intitial_addr = self.addr_counter
199             self.put_data_bytes(idx, 10, 'Page write')
200             num_bytes_to_write = len(self.packets[idx:])
201             if num_bytes_to_write > self.chip['page_size']:
202                 self.putb([0, ['Warning: Wrote %d bytes but page size is '
203                                'only %d bytes!' % (num_bytes_to_write,
204                                self.chip['page_size'])]])
205             page1 = int(intitial_addr / self.chip['page_size'])
206             page2 = int((self.addr_counter - 1) / self.chip['page_size'])
207             if page1 != page2:
208                 self.putb([0, ['Warning: Page write crossed page boundary '
209                                'from page %d to %d!' % (page1, page2)]])
210         elif self.is_cur_addr_read:
211             # Current address read: no word address, one data byte.
212             self.put_data_byte(self.packets[1])
213             self.put(self.packets[1][0], self.packets[-1][1], self.out_ann,
214                 [8, ['Data', 'D']])
215             self.putb([11, ['Current address read: %02X' % self.bytebuf[0],
216                        'Current address read', 'Cur addr read', 'CAR', 'C']])
217             self.putbin([0, bytes([self.bytebuf[0]])])
218             self.addr_counter += 1
219         elif self.is_random_access_read:
220             # Random access read: word address, one data byte.
221             self.put_control_word(self.packets[idx][4])
222             self.put_word_addr(self.packets)
223             self.put_data_bytes(idx + 1, 12, 'Random access read')
224         elif self.is_seq_random_read:
225             # Sequential random read: word address, two or more data bytes.
226             self.put_control_word(self.packets[idx][4])
227             self.put_word_addr(self.packets)
228             self.put_data_bytes(idx + 1, 13, 'Sequential random read')
229
230     def handle_wait_for_start(self):
231         # Wait for an I²C START condition.
232         if self.cmd not in ('START', 'START REPEAT'):
233             return
234         self.ss_block = self.ss
235         self.state = 'GET CONTROL WORD'
236
237     def handle_get_control_word(self):
238         # The packet after START must be an ADDRESS READ or ADDRESS WRITE.
239         if self.cmd not in ('ADDRESS READ', 'ADDRESS WRITE'):
240             self.reset()
241             return
242         self.packet_append()
243         self.put_control_word(self.bits)
244         self.state = '%s GET ACK NACK AFTER CONTROL WORD' % self.cmd[8]
245
246     def handle_r_get_ack_nack_after_control_word(self):
247         if self.cmd == 'ACK':
248             self.state = 'R GET WORD ADDR OR BYTE'
249         elif self.cmd == 'NACK':
250             self.es_block = self.es
251             self.putb([0, ['Warning: No reply from slave!']])
252             self.reset()
253         else:
254             self.reset()
255
256     def handle_r_get_word_addr_or_byte(self):
257         if self.cmd == 'STOP':
258             self.es_block = self.es
259             self.putb([0, ['Warning: Slave replied, but master aborted!']])
260             self.reset()
261             return
262         elif self.cmd != 'DATA READ':
263             self.reset()
264             return
265         self.packet_append()
266         self.state = 'R GET ACK NACK AFTER WORD ADDR OR BYTE'
267
268     def handle_r_get_ack_nack_after_word_addr_or_byte(self):
269         if self.cmd == 'ACK':
270             self.state = 'R GET RESTART'
271         elif self.cmd == 'NACK':
272             self.is_cur_addr_read = True
273             self.state = 'GET STOP AFTER LAST BYTE'
274         else:
275             self.reset()
276
277     def handle_r_get_restart(self):
278         if self.cmd == 'RESTART':
279             self.state = 'R READ BYTE'
280         else:
281             self.reset()
282
283     def handle_r_read_byte(self):
284         if self.cmd == 'DATA READ':
285             self.packet_append()
286             self.state = 'R GET ACK NACK AFTER BYTE WAS READ'
287         else:
288             self.reset()
289
290     def handle_r_get_ack_nack_after_byte_was_read(self):
291         if self.cmd == 'ACK':
292             self.state = 'R READ BYTE'
293         elif self.cmd == 'NACK':
294             # It's either a RANDOM READ or a SEQUENTIAL READ.
295             self.state = 'GET STOP AFTER LAST BYTE'
296         else:
297             self.reset()
298
299     def handle_w_get_ack_nack_after_control_word(self):
300         if self.cmd == 'ACK':
301             self.state = 'W GET WORD ADDR'
302         elif self.cmd == 'NACK':
303             self.es_block = self.es
304             self.putb([0, ['Warning: No reply from slave!']])
305             self.reset()
306         else:
307             self.reset()
308
309     def handle_w_get_word_addr(self):
310         if self.cmd == 'STOP':
311             self.es_block = self.es
312             self.putb([0, ['Warning: Slave replied, but master aborted!']])
313             self.reset()
314             return
315         elif self.cmd != 'DATA WRITE':
316             self.reset()
317             return
318         self.packet_append()
319         self.state = 'W GET ACK AFTER WORD ADDR'
320
321     def handle_w_get_ack_after_word_addr(self):
322         if self.cmd == 'ACK':
323             self.state = 'W DETERMINE EEPROM READ OR WRITE'
324         else:
325             self.reset()
326
327     def handle_w_determine_eeprom_read_or_write(self):
328         if self.cmd == 'START REPEAT':
329             # It's either a RANDOM ACCESS READ or SEQUENTIAL RANDOM READ.
330             self.state = 'R2 GET CONTROL WORD'
331         elif self.cmd == 'DATA WRITE':
332             self.packet_append()
333             self.state = 'W GET ACK NACK AFTER BYTE WAS WRITTEN'
334         else:
335             self.reset()
336
337     def handle_w_write_byte(self):
338         if self.cmd == 'DATA WRITE':
339             self.packet_append()
340             self.state = 'W GET ACK NACK AFTER BYTE WAS WRITTEN'
341         elif self.cmd == 'STOP':
342             if len(self.bytebuf) < 2:
343                 self.reset()
344                 return
345             self.es_block = self.es
346             if len(self.bytebuf) == 2:
347                 self.is_byte_write = True
348             else:
349                 self.is_page_write = True
350             self.put_operation()
351             self.reset()
352         elif self.cmd == 'START REPEAT':
353             # It's either a RANDOM ACCESS READ or SEQUENTIAL RANDOM READ.
354             self.state = 'R2 GET CONTROL WORD'
355         else:
356             self.reset()
357
358     def handle_w_get_ack_nack_after_byte_was_written(self):
359         if self.cmd == 'ACK':
360             self.state = 'W WRITE BYTE'
361         else:
362             self.reset()
363
364     def handle_r2_get_control_word(self):
365         if self.cmd == 'ADDRESS READ':
366             self.packet_append()
367             self.state = 'R2 GET ACK AFTER ADDR READ'
368         else:
369             self.reset()
370
371     def handle_r2_get_ack_after_addr_read(self):
372         if self.cmd == 'ACK':
373             self.state = 'R2 READ BYTE'
374         else:
375             self.reset()
376
377     def handle_r2_read_byte(self):
378         if self.cmd == 'DATA READ':
379             self.packet_append()
380             self.state = 'R2 GET ACK NACK AFTER BYTE WAS READ'
381         elif self.cmd == 'STOP':
382             self.decide_on_seq_or_rnd_read()
383             self.es_block = self.es
384             self.putb([0, ['Warning: STOP expected after a NACK (not ACK)']])
385             self.put_operation()
386             self.reset()
387         else:
388             self.reset()
389
390     def handle_r2_get_ack_nack_after_byte_was_read(self):
391         if self.cmd == 'ACK':
392             self.state = 'R2 READ BYTE'
393         elif self.cmd == 'NACK':
394             self.decide_on_seq_or_rnd_read()
395             self.state = 'GET STOP AFTER LAST BYTE'
396         else:
397             self.reset()
398
399     def handle_get_stop_after_last_byte(self):
400         if self.cmd == 'STOP':
401             self.es_block = self.es
402             self.put_operation()
403             self.reset()
404         elif self.cmd == 'START REPEAT':
405             self.es_block = self.es
406             self.putb([0, ['Warning: STOP expected (not RESTART)']])
407             self.put_operation()
408             self.reset()
409             self.ss_block = self.ss
410             self.state = 'GET CONTROL WORD'
411         else:
412             self.reset()
413
414     def decode(self, ss, es, data):
415         self.cmd, self.databyte = data
416
417         # Collect the 'BITS' packet, then return. The next packet is
418         # guaranteed to belong to these bits we just stored.
419         if self.cmd == 'BITS':
420             self.bits = self.databyte
421             return
422
423         # Store the start/end samples of this I²C packet.
424         self.ss, self.es = ss, es
425
426         # State machine.
427         s = 'handle_%s' % self.state.lower().replace(' ', '_')
428         handle_state = getattr(self, s)
429         handle_state()