decoders/adf435x/pd.py

   1 ##
   2 ## This file is part of the libsigrokdecode project.
   3 ##
   4 ## Copyright (C) 2017 Joel Holdsworth <joel@airwebreathe.org.uk>
   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 3 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 common.srdhelper import bitpack_lsb
  22
  23 def disabled_enabled(v):
  24     return ['Disabled', 'Enabled'][v]
  25
  26 def output_power(v):
  27     return '{:+d}dBm'.format([-4, -1, 2, 5][v])
  28
  29 # Notes on the implementation:
  30 # - A register's description is an iterable of tuples which contain:
  31 #   The starting bit position, the bit count, the name of a field, and
  32 #   an optional parser which interprets the field's content. Parser are
  33 #   expected to yield a single text string when they exist. Other types
  34 #   of output are passed to Python's .format() routine as is.
  35 # - Bit fields' width in registers determines the range of indices in
  36 #   table/tuple lookups. Keep the implementation as robust as possible
  37 #   during future maintenance. Avoid Python runtime errors when adjusting
  38 #   the decoder.
  39 regs = {
  40     # Register description fields:
  41     # offset, width, name, parser.
  42     0: (
  43         ( 3, 12, 'FRAC'),
  44         (15, 16, 'INT',
  45             None, lambda v: 'Not Allowed' if v < 23 else None,
  46         ),
  47     ),
  48     1: (
  49         ( 3, 12, 'MOD'),
  50         (15, 12, 'Phase'),
  51         (27,  1, 'Prescalar', lambda v: ('4/5', '8/9',)[v]),
  52         (28,  1, 'Phase Adjust', lambda v: ('Off', 'On',)[v]),
  53     ),
  54     2: (
  55         ( 3,  1, 'Counter Reset', disabled_enabled),
  56         ( 4,  1, 'Charge Pump Three-State', disabled_enabled),
  57         ( 5,  1, 'Power-Down', disabled_enabled),
  58         ( 6,  1, 'PD Polarity', lambda v: ('Negative', 'Positive',)[v]),
  59         ( 7,  1, 'LDP', lambda v: ('10ns', '6ns',)[v]),
  60         ( 8,  1, 'LDF', lambda v: ('FRAC-N', 'INT-N',)[v]),
  61         ( 9,  4, 'Charge Pump Current Setting',
  62             lambda v: '{curr:0.2f}mA @ 5.1kΩ'.format(curr = (
  63                 0.31, 0.63, 0.94, 1.25, 1.56, 1.88, 2.19, 2.50,
  64                 2.81, 3.13, 3.44, 3.75, 4.06, 4.38, 4.69, 5.00,
  65             )[v])),
  66         (13,  1, 'Double Buffer', disabled_enabled),
  67         (14, 10, 'R Counter'),
  68         (24,  1, 'RDIV2', disabled_enabled),
  69         (25,  1, 'Reference Doubler', disabled_enabled),
  70         (26,  3, 'MUXOUT',
  71             lambda v: '{text}'.format(text = (
  72                 'Three-State Output', 'DVdd', 'DGND',
  73                 'R Counter Output', 'N Divider Output',
  74                 'Analog Lock Detect', 'Digital Lock Detect',
  75                 'Reserved',
  76             )[v])),
  77         (29,  2, 'Low Noise and Low Spur Modes',
  78             lambda v: '{text}'.format(text = (
  79                 'Low Noise Mode', 'Reserved', 'Reserved', 'Low Spur Mode',
  80             )[v])),
  81     ),
  82     3: (
  83         ( 3, 12, 'Clock Divider'),
  84         (15,  2, 'Clock Divider Mode',
  85             lambda v: '{text}'.format(text = (
  86                 'Clock Divider Off', 'Fast Lock Enable',
  87                 'Resync Enable', 'Reserved',
  88             )[v])),
  89         (18,  1, 'CSR Enable', disabled_enabled),
  90         (21,  1, 'Charge Cancellation', disabled_enabled),
  91         (22,  1, 'ABP', lambda v: ('6ns (FRAC-N)', '3ns (INT-N)',)[v]),
  92         (23,  1, 'Band Select Clock Mode', lambda v: ('Low', 'High',)[v]),
  93     ),
  94     4: (
  95         ( 3,  2, 'Output Power', output_power),
  96         ( 5,  1, 'Output Enable', disabled_enabled),
  97         ( 6,  2, 'AUX Output Power', output_power),
  98         ( 8,  1, 'AUX Output Select',
  99             lambda v: ('Divided Output', 'Fundamental',)[v]),
 100         ( 9,  1, 'AUX Output Enable', disabled_enabled),
 101         (10,  1, 'MTLD', disabled_enabled),
 102         (11,  1, 'VCO Power-Down',
 103             lambda v: 'VCO Powered {ud}'.format(ud = 'Down' if v else 'Up')),
 104         (12,  8, 'Band Select Clock Divider'),
 105         (20,  3, 'RF Divider Select', lambda v: '÷{:d}'.format(2 ** v)),
 106         (23,  1, 'Feedback Select', lambda v: ('Divided', 'Fundamental',)[v]),
 107     ),
 108     5: (
 109         (22,  2, 'LD Pin Mode',
 110             lambda v: '{text}'.format(text = (
 111                 'Low', 'Digital Lock Detect', 'Low', 'High',
 112             )[v])),
 113     ),
 114 }
 115
 116 ( ANN_REG, ANN_WARN, ) = range(2)
 117
 118 class Decoder(srd.Decoder):
 119     api_version = 3
 120     id = 'adf435x'
 121     name = 'ADF435x'
 122     longname = 'Analog Devices ADF4350/1'
 123     desc = 'Wideband synthesizer with integrated VCO.'
 124     license = 'gplv3+'
 125     inputs = ['spi']
 126     outputs = []
 127     tags = ['Clock/timing', 'IC', 'Wireless/RF']
 128     annotations = (
 129         # Sent from the host to the chip.
 130         ('write', 'Register write'),
 131         ('warning', "Warnings"),
 132     )
 133     annotation_rows = (
 134         ('writes', 'Register writes', (ANN_REG,)),
 135         ('warnings', 'Warnings', (ANN_WARN,)),
 136     )
 137
 138     def __init__(self):
 139         self.reset()
 140
 141     def reset(self):
 142         self.bits = []
 143
 144     def start(self):
 145         self.out_ann = self.register(srd.OUTPUT_ANN)
 146
 147     def putg(self, ss, es, cls, data):
 148         self.put(ss, es, self.out_ann, [ cls, data, ])
 149
 150     def decode_bits(self, offset, width):
 151         '''Extract a bit field. Expects LSB input data.'''
 152         bits = self.bits[offset:][:width]
 153         ss, es = bits[-1][1], bits[0][2]
 154         value = bitpack_lsb(bits, 0)
 155         return ( value, ( ss, es, ))
 156
 157     def decode_field(self, name, offset, width, parser = None, checker = None):
 158         '''Interpret a bit field. Emits an annotation.'''
 159         # Get the register field's content and position.
 160         val, ( ss, es, ) = self.decode_bits(offset, width)
 161         # Have the field's content formatted, emit an annotation.
 162         formatted = parser(val) if parser else '{}'.format(val)
 163         if formatted is not None:
 164             text = ['{name}: {val}'.format(name = name, val = formatted)]
 165         else:
 166             text = ['{name}'.format(name = name)]
 167         if text:
 168             self.putg(ss, es, ANN_REG, text)
 169         # Have the field's content checked, emit an optional warning.
 170         warn = checker(val) if checker else None
 171         if warn:
 172             text = ['{}'.format(warn)]
 173             self.putg(ss, es, ANN_WARN, text)
 174
 175     def decode_word(self, ss, es, bits):
 176         '''Interpret a 32bit word after accumulation completes.'''
 177         # SPI transfer content must be exactly one 32bit word.
 178         count = len(self.bits)
 179         if count != 32:
 180             text = [
 181                 'Frame error: Bit count: want 32, got {}'.format(count),
 182                 'Frame error: Bit count',
 183                 'Frame error',
 184             ]
 185             self.putg(ss, es, ANN_WARN, text)
 186             return
 187         # Holding bits in LSB order during interpretation simplifies
 188         # bit field extraction. And annotation emitting routines expect
 189         # this reverse order of bits' timestamps.
 190         self.bits.reverse()
 191         # Determine which register was accessed.
 192         reg_addr, ( reg_ss, reg_es, ) = self.decode_bits(0, 3)
 193         text = [
 194             'Register: {addr}'.format(addr = reg_addr),
 195             'Reg: {addr}'.format(addr = reg_addr),
 196             '[{addr}]'.format(addr = reg_addr),
 197         ]
 198         self.putg(reg_ss, reg_es, ANN_REG, text)
 199         # Interpret the register's content (when parsers are available).
 200         field_descs = regs.get(reg_addr, None)
 201         if not field_descs:
 202             return
 203         for field_desc in field_descs:
 204             parser = None
 205             checker = None
 206             if len(field_desc) == 3:
 207                 start, count, name, = field_desc
 208             elif len(field_desc) == 4:
 209                 start, count, name, parser = field_desc
 210             elif len(field_desc) == 5:
 211                 start, count, name, parser, checker = field_desc
 212             else:
 213                 # Unsupported regs{} syntax, programmer's error.
 214                 return
 215             self.decode_field(name, start, count, parser, checker)
 216
 217     def decode(self, ss, es, data):
 218         ptype, _, _ = data
 219
 220         if ptype == 'TRANSFER':
 221             # Process accumulated bits after completion of a transfer.
 222             self.decode_word(ss, es, self.bits)
 223             self.bits.clear()
 224
 225         if ptype == 'BITS':
 226             _, mosi_bits, miso_bits = data
 227             # Accumulate bits in MSB order as they are seen in SPI frames.
 228             msb_bits = mosi_bits.copy()
 229             msb_bits.reverse()
 230             self.bits.extend(msb_bits)