Decoder.output_new() now takes an extra protocol_id argument.
[libsigrokdecode.git] / decoders / i2c.py
index 16e74913deb27a1799fd847f4d1c1efd54e2498a..23b12c34f4791720067d068f82627aa42dd60972 100644 (file)
 # 'data': (actual data as integer ???) TODO: This can be very variable...
 # 'ann': (string; additional annotations / comments)
 #
-# Example output:
-# [{'type': 'S',  'range': (150, 160), 'data': None, 'ann': 'Foobar'},
-#  {'type': 'AW', 'range': (200, 300), 'data': 0x50, 'ann': 'Slave 4'},
-#  {'type': 'DW', 'range': (310, 370), 'data': 0x00, 'ann': 'Init cmd'},
-#  {'type': 'AR', 'range': (500, 560), 'data': 0x50, 'ann': 'Get stat'},
-#  {'type': 'DR', 'range': (580, 640), 'data': 0xfe, 'ann': 'OK'},
-#  {'type': 'P',  'range': (650, 660), 'data': None, 'ann': None}]
-#
-# Possible other events:
-#   - Error event in case protocol looks broken:
-#     [{'type': 'ERROR', 'range': (min, max),
-#      'data': TODO, 'ann': 'This is not a Microchip 24XX64 EEPROM'},
-#     [{'type': 'ERROR', 'range': (min, max),
-#      'data': TODO, 'ann': 'TODO'},
-#   - TODO: Make list of possible errors accessible as metadata?
-#
 # TODO: I2C address of slaves.
 # TODO: Handle multiple different I2C devices on same bus
 #       -> we need to decode multiple protocols at the same time.
-# TODO: range: Always contiguous? Splitted ranges? Multiple per event?
 #
 
 #
 #  'signals': [{'SCL': }]}
 #
 
+import sigrokdecode
+
+# values are verbose and short annotation, respectively
+protocol = {
+    'START':           ['START',        'S'],
+    'START_REPEAT':    ['START REPEAT', 'Sr'],
+    'STOP':            ['STOP',         'P'],
+    'ACK':             ['ACK',          'A'],
+    'NACK':            ['NACK',         'N'],
+    'ADDRESS_READ':    ['ADDRESS READ', 'AR'],
+    'ADDRESS_WRITE':   ['ADDRESS WRITE','AW'],
+    'DATA_READ':       ['DATA READ',    'DR'],
+    'DATA_WRITE':      ['DATA WRITE',   'DW'],
+}
+# export protocol keys as symbols for i2c decoders up the stack
+EXPORT = [ protocol.keys() ]
+
 # States
 FIND_START = 0
 FIND_ADDRESS = 1
 FIND_DATA = 2
 
-class Sample():
-    def __init__(self, data):
-        self.data = data
-    def probe(self, probe):
-        s = ord(self.data[probe / 8]) & (1 << (probe % 8))
-        return True if s else False
+# annotation feed formats
+ANN_SHIFTED       = 0
+ANN_SHIFTED_SHORT = 1
+ANN_RAW           = 2
 
-def sampleiter(data, unitsize):
-    for i in range(0, len(data), unitsize):
-        yield(Sample(data[i:i+unitsize]))
 
-class Decoder():
+class Decoder(sigrokdecode.Decoder):
     id = 'i2c'
     name = 'I2C'
     longname = 'Inter-Integrated Circuit (I2C) bus'
@@ -153,38 +148,40 @@ class Decoder():
     license = 'gplv2+'
     inputs = ['logic']
     outputs = ['i2c']
-    probes = {
-        'scl': {'ch': 0, 'name': 'SCL', 'desc': 'Serial clock line'},
-        'sda': {'ch': 1, 'name': 'SDA', 'desc': 'Serial data line'},
-    }
+    probes = [
+        {'id': 'scl', 'name': 'SCL', 'desc': 'Serial clock line'},
+        {'id': 'sda', 'name': 'SDA', 'desc': 'Serial data line'},
+    ]
     options = {
         'address-space': ['Address space (in bits)', 7],
     }
+    annotation = [
+        # ANN_SHIFTED
+        ["7-bit shifted hex",
+         "Read/Write bit shifted out from the 8-bit i2c slave address"],
+        # ANN_SHIFTED_SHORT
+        ["7-bit shifted hex (short)",
+         "Read/Write bit shifted out from the 8-bit i2c slave address"],
+        # ANN_RAW
+        ["Raw hex", "Unaltered raw data"]
+    ]
 
     def __init__(self, **kwargs):
-        self.probes = Decoder.probes.copy()
-
-        # TODO: Don't hardcode the number of channels.
-        self.channels = 8
-
-        self.samplenum = 0
+        self.output_protocol = None
+        self.output_annotation = None
+        self.samplecnt = 0
         self.bitcount = 0
         self.databyte = 0
         self.wr = -1
         self.startsample = -1
         self.is_repeat_start = 0
-
         self.state = FIND_START
-
-        # Get the channel/probe number of the SCL/SDA signals.
-        self.scl_bit = self.probes['scl']['ch']
-        self.sda_bit = self.probes['sda']['ch']
-
         self.oldscl = None
         self.oldsda = None
 
     def start(self, metadata):
-        self.unitsize = metadata["unitsize"]
+        self.output_protocol = self.output_new(1, 'i2c')
+        self.output_annotation = self.output_new(0, 'i2c')
 
     def report(self):
         pass
@@ -207,24 +204,26 @@ class Decoder():
             return True
         return False
 
-    def find_start(self, scl, sda):
-        out = []
-        # o = {'type': 'S', 'range': (self.samplenum, self.samplenum),
-        #      'data': None, 'ann': None},
-        o = (self.is_repeat_start == 1) and 'Sr' or 'S'
-        out.append(o)
+    def found_start(self, scl, sda):
+        if self.is_repeat_start == 1:
+            cmd = 'START_REPEAT'
+        else:
+            cmd = 'START'
+        self.put(self.output_protocol, [ cmd ])
+        self.put(self.output_annotation, [ ANN_SHIFTED, [protocol[cmd][0]] ])
+        self.put(self.output_annotation, [ ANN_SHIFTED_SHORT, [protocol[cmd][1]] ])
+
         self.state = FIND_ADDRESS
         self.bitcount = self.databyte = 0
         self.is_repeat_start = 1
         self.wr = -1
-        return out
 
-    def find_address_or_data(self, scl, sda):
+    def found_address_or_data(self, scl, sda):
         """Gather 8 bits of data plus the ACK/NACK bit."""
-        out = o = []
 
         if self.startsample == -1:
-            self.startsample = self.samplenum
+            # TODO: should be samplenum, as received from the feed
+            self.startsample = self.samplecnt
         self.bitcount += 1
 
         # Address and data are transmitted MSB-first.
@@ -235,43 +234,50 @@ class Decoder():
         if self.bitcount != 9:
             return []
 
+        # send raw output annotation before we start shifting out
+        # read/write and ack/nack bits
+        self.put(self.output_annotation, [ANN_RAW, ["0x%.2x" % self.databyte]])
+
         # We received 8 address/data bits and the ACK/NACK bit.
         self.databyte >>= 1 # Shift out unwanted ACK/NACK bit here.
 
-        ack = (sda == 1) and 'N' or 'A'
-
         if self.state == FIND_ADDRESS:
             d = self.databyte & 0xfe
             # The READ/WRITE bit is only in address bytes, not data bytes.
-            self.wr = (self.databyte & 1) and 1 or 0
+            self.wr = 1 if (self.databyte & 1) else 0
         elif self.state == FIND_DATA:
             d = self.databyte
         else:
             # TODO: Error?
             pass
 
-        # o = {'type': self.state,
-        #      'range': (self.startsample, self.samplenum - 1),
-        #      'data': d, 'ann': None}
-
-        o = {'data': '0x%02x' % d}
+        # last bit that came in was the ACK/NACK bit (1 = NACK)
+        if sda == 1:
+            ack_bit = 'NACK'
+        else:
+            ack_bit = 'ACK'
 
         # TODO: Simplify.
         if self.state == FIND_ADDRESS and self.wr == 1:
-            o['type'] = 'AW'
+            cmd = 'ADDRESS_WRITE'
         elif self.state == FIND_ADDRESS and self.wr == 0:
-            o['type'] = 'AR'
+            cmd = 'ADDRESS_READ'
         elif self.state == FIND_DATA and self.wr == 1:
-            o['type'] = 'DW'
+            cmd = 'DATA_WRITE'
         elif self.state == FIND_DATA and self.wr == 0:
-            o['type'] = 'DR'
-
-        out.append(o)
+            cmd = 'DATA_READ'
+        self.put(self.output_protocol, [ [cmd, d], [ack_bit] ] )
+        self.put(self.output_annotation, [ANN_SHIFTED, [
+                "%s" % protocol[cmd][0],
+                "0x%02x" % d,
+                "%s" % protocol[ack_bit][0]]
+            ] )
+        self.put(self.output_annotation, [ANN_SHIFTED_SHORT, [
+                "%s" % protocol[cmd][1],
+                "0x%02x" % d,
+                "%s" % protocol[ack_bit][1]]
+            ] )
 
-        # o = {'type': ack, 'range': (self.samplenum, self.samplenum),
-        #      'data': None, 'ann': None}
-        o = ack
-        out.append(o)
         self.bitcount = self.databyte = 0
         self.startsample = -1
 
@@ -282,63 +288,46 @@ class Decoder():
             # So, either find a STOP condition or another data byte next.
             pass
 
-        return out
+    def found_stop(self, scl, sda):
+        self.put(self.output_protocol, [ 'STOP' ])
+        self.put(self.output_annotation, [ ANN_SHIFTED, [protocol['STOP'][0]] ])
+        self.put(self.output_annotation, [ ANN_SHIFTED_SHORT, [protocol['STOP'][1]] ])
 
-    def find_stop(self, scl, sda):
-        out = o = []
-
-        # o = {'type': 'P', 'range': (self.samplenum, self.samplenum),
-        #      'data': None, 'ann': None},
-        o = 'P'
-        out.append(o)
         self.state = FIND_START
         self.is_repeat_start = 0
         self.wr = -1
 
-        return out
-
-    def decode(self, data):
-        """I2C protocol decoder"""
-
-        out = []
-        o = ack = d = ''
+    def put(self, output_id, data):
+        # inject sample range into the call up to sigrok
+        # TODO: 0-0 sample range for now
+        super(Decoder, self).put(0, 0, output_id, data)
 
-        # We should accept a list of samples and iterate...
-        for sample in sampleiter(data['data'], self.unitsize):
-
-            # TODO: Eliminate the need for ord().
-            s = ord(sample.data)
-
-            # TODO: Start counting at 0 or 1?
-            self.samplenum += 1
+    def decode(self, timeoffset, duration, data):
+        for samplenum, (scl, sda) in data:
+            self.samplecnt += 1
 
             # First sample: Save SCL/SDA value.
             if self.oldscl == None:
-                # Get SCL/SDA bit values (0/1 for low/high) of the first sample.
-                self.oldscl = (s & (1 << self.scl_bit)) >> self.scl_bit
-                self.oldsda = (s & (1 << self.sda_bit)) >> self.sda_bit
+                self.oldscl = scl
+                self.oldsda = sda
                 continue
 
-            # Get SCL/SDA bit values (0/1 for low/high).
-            scl = (s & (1 << self.scl_bit)) >> self.scl_bit
-            sda = (s & (1 << self.sda_bit)) >> self.sda_bit
-
             # TODO: Wait until the bus is idle (SDA = SCL = 1) first?
 
             # State machine.
             if self.state == FIND_START:
                 if self.is_start_condition(scl, sda):
-                    out += self.find_start(scl, sda)
+                    self.found_start(scl, sda)
             elif self.state == FIND_ADDRESS:
                 if self.is_data_bit(scl, sda):
-                    out += self.find_address_or_data(scl, sda)
+                    self.found_address_or_data(scl, sda)
             elif self.state == FIND_DATA:
                 if self.is_data_bit(scl, sda):
-                    out += self.find_address_or_data(scl, sda)
+                    self.found_address_or_data(scl, sda)
                 elif self.is_start_condition(scl, sda):
-                    out += self.find_start(scl, sda)
+                    self.found_start(scl, sda)
                 elif self.is_stop_condition(scl, sda):
-                    out += self.find_stop(scl, sda)
+                    self.found_stop(scl, sda)
             else:
                 # TODO: Error?
                 pass
@@ -347,10 +336,3 @@ class Decoder():
             self.oldscl = scl
             self.oldsda = sda
 
-        if out != []:
-            sigrok.put(out)
-
-import sigrok
-
-sigrok.register(Decoder)
-