summaryrefslogtreecommitdiffstats
path: root/libtoprammer/chip.py
blob: ae6761cba80fb786007825fd56c4d24c923d5803 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
"""
#    TOP2049 Open Source programming suite
#
#    Chip support
#
#    Copyright (c) 2009-2012 Michael Buesch <m@bues.ch>
#
#    This program is free software; you can redistribute it and/or modify
#    it under the terms of the GNU General Public License as published by
#    the Free Software Foundation; either version 2 of the License, or
#    (at your option) any later version.
#
#    This program is distributed in the hope that it will be useful,
#    but WITHOUT ANY WARRANTY; without even the implied warranty of
#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#    GNU General Public License for more details.
#
#    You should have received a copy of the GNU General Public License along
#    with this program; if not, write to the Free Software Foundation, Inc.,
#    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
"""

from util import *
from layout_generator import *
from user_interface import *
from generic_algorithms import *
from ihex import *


class Chip(object):
	SUPPORT_ERASE		= (1 << 0)
	SUPPORT_SIGREAD		= (1 << 1)
	SUPPORT_PROGMEMREAD	= (1 << 2)
	SUPPORT_PROGMEMWRITE	= (1 << 3)
	SUPPORT_EEPROMREAD	= (1 << 4)
	SUPPORT_EEPROMWRITE	= (1 << 5)
	SUPPORT_FUSEREAD	= (1 << 6)
	SUPPORT_FUSEWRITE	= (1 << 7)
	SUPPORT_LOCKREAD	= (1 << 8)
	SUPPORT_LOCKWRITE	= (1 << 9)
	SUPPORT_RAMREAD		= (1 << 10)
	SUPPORT_RAMWRITE	= (1 << 11)
	SUPPORT_TEST		= (1 << 12)
	SUPPORT_UILREAD		= (1 << 13)
	SUPPORT_UILWRITE	= (1 << 14)

	@classmethod
	def chipSupportsAttr(cls, methodName):
		"""Check if a chip implementation supports a feature.
		'methodName' is the class member function to check for"""
		# This works by checking whether the subclass overloaded
		# the member function attribute.
		return getattr(cls, methodName) != getattr(Chip, methodName)

	@classmethod
	def getSupportFlags(cls):
		"Get the SUPPORT_... flags for this chip"
		flags = 0
		for (methodName, flag) in (
				("erase",		cls.SUPPORT_ERASE),
				("readSignature",	cls.SUPPORT_SIGREAD),
				("readProgmem",		cls.SUPPORT_PROGMEMREAD),
				("writeProgmem",	cls.SUPPORT_PROGMEMWRITE),
				("readEEPROM",		cls.SUPPORT_EEPROMREAD),
				("writeEEPROM",		cls.SUPPORT_EEPROMWRITE),
				("readFuse",		cls.SUPPORT_FUSEREAD),
				("writeFuse",		cls.SUPPORT_FUSEWRITE),
				("readLockbits",	cls.SUPPORT_LOCKREAD),
				("writeLockbits",	cls.SUPPORT_LOCKWRITE),
				("readRAM",		cls.SUPPORT_RAMREAD),
				("writeRAM",		cls.SUPPORT_RAMWRITE),
				("test",		cls.SUPPORT_TEST),
				("readUserIdLocation",	cls.SUPPORT_UILREAD),
				("writeUserIdLocation",		cls.SUPPORT_UILWRITE)):
			
			if cls.chipSupportsAttr(methodName):
				flags |= flag
		return flags

	@classmethod
	def createInstance(cls, top, chipDescription, assignedChipOptions=()):
		instance = cls()
		instance.top = top
		instance.chipDescription = chipDescription
		for acopt in assignedChipOptions:
			copt = chipDescription.getChipOption(acopt.name)
			if not copt:
				raise TOPException("'%s' is not a valid chip option "
					"for chip ID '%s'" %\
					(acopt.name, chipDescription.chipID))
			acopt.detectAndVerifyType(copt)
		instance.assignedChipOptions = assignedChipOptions
		instance.generateVoltageLayouts()
		return instance

	def __init__(self, chipPackage=None, chipPinVCC=None, chipPinsVPP=None, chipPinGND=None):
		"""chipPackage is the ID string for the package.
		May be None, if no initial auto-layout is required.
		chipPinVCC is the required VCC pin on the package.
		chipPinsVPP is the required VPP pin on the package.
		chipPinGND is the required GND pin on the package."""

		self.__chipPackage = chipPackage
		self.__chipPinVCC = chipPinVCC
		self.__chipPinsVPP = chipPinsVPP
		self.__chipPinGND = chipPinGND

	def printWarning(self, message):
		self.top.printWarning(self.chipDescription.chipID +\
				      ": Warning - " + message)

	def printInfo(self, message):
		self.top.printInfo(self.chipDescription.chipID +\
				   ": " + message)

	def printDebug(self, message):
		self.top.printDebug(self.chipDescription.chipID +\
				    ": Debug - " + message)

	def throwError(self, message):
		raise TOPException(self.chipDescription.chipID +\
				   ": " + message)

	def generateVoltageLayouts(self):
		if self.__chipPackage:
			self.generator = createLayoutGenerator(self.__chipPackage)
			self.generator.setProgrammerType(self.top.getProgrammerType())
			self.generator.setPins(vccPin=self.__chipPinVCC,
					       vppPins=self.__chipPinsVPP,
					       gndPin=self.__chipPinGND)
			self.generator.recalculate()

	def getLayoutGenerator(self):
		if self.__chipPackage:
			return self.generator
		return None

	def applyVCC(self, turnOn):
		"Turn VCC on, using the auto-layout."
		if turnOn:
			try:
				generator = self.generator
			except (AttributeError), e:
				self.throwError("BUG: Using auto-layout, but did not initialize it.")
			generator.applyVCCLayout(self.top)
		else:
			self.top.vcc.setLayoutMask(0)

	def applyVPP(self, turnOn, packagePinsToTurnOn=[]):
		"""Turn VPP on, using the auto-layout.
		packagePinsToTurnOn is a list of pins on the package to drive to VPP.
		If it is not passed (or an empty list), all VPP pins of the layout are turned on.
		The parameter is unused, if turnOn=False."""
		if turnOn:
			try:
				generator = self.generator
			except (AttributeError), e:
				self.throwError("BUG: Using auto-layout, but did not initialize it.")
			generator.applyVPPLayout(self.top, packagePinsToTurnOn)
		else:
			self.top.vpp.setLayoutMask(0)

	def applyGND(self, turnOn):
		"Turn GND on, using the auto-layout."
		if turnOn:
			try:
				generator = self.generator
			except (AttributeError), e:
				self.throwError("BUG: Using auto-layout, but did not initialize it.")
			generator.applyGNDLayout(self.top)
		else:
			self.top.gnd.setLayoutMask(0)

	def progressMeterInit(self, message, nrSteps):
		self.top.progressMeterInit(AbstractUserInterface.PROGRESSMETER_CHIPACCESS,
					   message, nrSteps)

	def progressMeterFinish(self):
		self.top.progressMeterFinish(AbstractUserInterface.PROGRESSMETER_CHIPACCESS)

	def progressMeter(self, step):
		self.top.progressMeter(AbstractUserInterface.PROGRESSMETER_CHIPACCESS,
				       step)

	def getChipOptionValue(self, name, default=None):
		"""Get an AssignedChipOption value that was set by the user.
		If no such option is found, it returns 'default'."""
		name = name.lower()
		for acopt in self.assignedChipOptions:
			if acopt.name.lower() == name:
				return acopt.value
		return default

	def shutdownChip(self):
		# Override me in the subclass, if required.
		self.printDebug("Default chip shutdown")
		GenericAlgorithms(self).simpleVoltageShutdown()

	def getIHexInterpreter(self):
		# Returns the IHEX file interpreter.
		# This defaults to the non-section interpreter.
		# Override me in the subclass, if required.
		return IHexInterpreter()

	def readSignature(self):
		# Override me in the subclass, if required.
		self.throwError("Signature reading not supported")

	def erase(self):
		# Override me in the subclass, if required.
		self.throwError("Chip erasing not supported")

	def test(self):
		# Override me in the subclass, if required.
		self.throwError("Chip testing not supported")

	def readProgmem(self):
		# Override me in the subclass, if required.
		self.throwError("Program memory reading not supported")

	def writeProgmem(self, image):
		# Override me in the subclass, if required.
		self.throwError("Program memory writing not supported")

	def readEEPROM(self):
		# Override me in the subclass, if required.
		self.throwError("EEPROM reading not supported")

	def writeEEPROM(self, image):
		# Override me in the subclass, if required.
		self.throwError("EEPROM writing not supported")

	def readFuse(self):
		# Override me in the subclass, if required.
		self.throwError("Fuse reading not supported")

	def writeFuse(self, image):
		# Override me in the subclass, if required.
		self.throwError("Fuse writing not supported")

	def readLockbits(self):
		# Override me in the subclass, if required.
		self.throwError("Lockbit reading not supported")

	def writeLockbits(self, image):
		# Override me in the subclass, if required.
		self.throwError("Lockbit writing not supported")

	def readRAM(self):
		# Override me in the subclass, if required.
		self.throwError("RAM reading not supported")

	def writeRAM(self, image):
		# Override me in the subclass, if required.
		self.throwError("RAM writing not supported")
		
	def readUserIdLocation(self):
		# Override me in the subclass, if required.
		self.throwError("User ID Location reading not supported")

	def writeUserIdLocation(self, image):
		# Override me in the subclass, if required.
		self.throwError("User ID Location writing not supported")		

__registeredChips = []

def getRegisteredChips():
	"Get a list of registered ChipDescriptions"
	return __registeredChips

def getRegisteredVendors():
	"Returns a dict of 'vendor : [descriptor, ...]' "
	vendors = { }
	for descriptor in getRegisteredChips():
		for vendor in descriptor.chipVendors:
			vendors.setdefault(vendor, []).append(descriptor)
	return vendors

def _registerChip(chipDesc):
	regList = getRegisteredChips()
	if chipDesc.chipID in [ cd.chipID for cd in regList ]:
		raise TOPException("Chip description registration: "
			"The chipID '%s' is not unique." %\
			chipDesc.chipID)
	regList.append(chipDesc)

class BitDescription:
	def __init__(self, bitNr, description):
		self.bitNr = bitNr
		self.description = description

class ChipOption(object):
	TYPE_UNKNOWN	= "unknown"
	TYPE_BOOL	= "bool"
	TYPE_INT	= "int"
	TYPE_FLOAT	= "float"

	def __init__(self, optType, name, description=""):
		self.optType = optType
		self.name = name
		self.description = description

	def __repr__(self):
		desc = " / " + self.description if self.description else ""
		return "%s (%s%s)" % (self.name, self.optType, desc)

	def castValue(self, string):
		return None

class ChipOptionBool(ChipOption):
	def __init__(self, name, description=""):
		ChipOption.__init__(self, ChipOption.TYPE_BOOL,
				    name, description)

	def castValue(self, string):
		return str2bool(string)

class ChipOptionInt(ChipOption):
	def __init__(self, name, description="", minVal=None, maxVal=None):
		ChipOption.__init__(self, ChipOption.TYPE_INT,
				    name, description)
		self.minVal = int(minVal) if minVal is not None else None
		self.maxVal = int(maxVal) if minVal is not None else None

	def __limitError(self, value):
		raise TOPException("%s: Value exceeds limits: %d <= %d <= %d" %\
			(self.name, self.minVal, value, self.maxVal))

	def castValue(self, string):
		try:
			value = int(string)
		except (ValueError), e:
			return None
		if (self.minVal is not None and value < self.minVal) or\
		   (self.maxVal is not None and value > self.maxVal):
			self.__limitError(value)
		return value

class ChipOptionFloat(ChipOption):
	def __init__(self, name, description="", minVal=None, maxVal=None):
		ChipOption.__init__(self, ChipOption.TYPE_FLOAT,
				    name, description)
		self.minVal = float(minVal) if minVal is not None else None
		self.maxVal = float(maxVal) if minVal is not None else None

	def __limitError(self, value):
		raise TOPException("%s: Value exceeds limits: %f <= %f <= %f" %\
			(self.name, self.minVal, value, self.maxVal))

	def castValue(self, string):
		try:
			value = float(string)
		except (ValueError), e:
			return None
		if (self.minVal is not None and value < self.minVal) or\
		   (self.maxVal is not None and value > self.maxVal):
			self.__limitError(value)
		return value

class AssignedChipOption(ChipOption):
	def __init__(self, name, value):
		ChipOption.__init__(self, ChipOption.TYPE_UNKNOWN, name)
		self.value = value

	def detectAndVerifyType(self, baseOption):
		assert(baseOption.optType != self.TYPE_UNKNOWN)
		if self.optType != self.TYPE_UNKNOWN:
			return
		value = baseOption.castValue(self.value)
		if value is None:
			raise TOPException("Chip option '%s' type mismatch. "
				"Must be '%s'." %\
				(self.name, baseOption.optType))
		self.optType = baseOption.optType
		self.value = value

class ChipDescription:
	# Possible chip types
	TYPE_MCU	= 0	# Microcontroller
	TYPE_EPROM	= 1	# EPROM
	TYPE_EEPROM	= 2	# EEPROM
	TYPE_GAL	= 3	# PAL/GAL
	TYPE_SRAM	= 4	# Static RAM
	TYPE_LOGIC	= 5	# Logics chip
	TYPE_INTERNAL	= 999	# For internal use only

	def __init__(self, chipImplClass, bitfile, chipID="",
		     runtimeID=(0,0),
		     chipType=TYPE_MCU,
		     chipVendors="Other",
		     description="", fuseDesc=(), lockbitDesc=(),
		     packages=None, comment="",
		     chipOptions=(),
		     maintainer="Michael Buesch <m@bues.ch>",
		     broken=False):
		"""Chip implementation class description.
		chipImplClass	=> The implementation class of the chip.
		bitfile		=> The name of the default bitfile loaded on initialization.
		chipID		=> The chip-ID string. Will default to the bitfile ID string.
		runtimeID	=> The runtime-ID is a tuple of two numbers that uniquely
				   identifies a loaded FPGA configuration. The first number in the
				   tuple is an ID number and the second number is a revision number.
		chipType	=> Chip type. Defaults to MCU.
		chipVendors	=> The chip vendor name(s).
		description	=> Human readable chip description string.
		fuseDesc	=> Tuple of fuse bits descriptions (BitDescription(), ...)
		lockbitDesc	=> Tuple of lock bits descriptions (BitDescription(), ...)
		packages	=> List of supported packages.
				   Each entry is a tuple of two strings: ("PACKAGE", "description")
		comment		=> Additional comment string.
		chipOptions	=> Tuple of ChipOption instances, if any.
		maintainer	=> Maintainer name.
		broken		=> Boolean flag to mark the implementation as broken.
		"""

		if not chipID:
			chipID = bitfile
		if isinstance(chipVendors, str):
			chipVendors = (chipVendors, )
		self.chipImplClass = chipImplClass
		self.bitfile = bitfile
		self.chipID = chipID
		self.runtimeID = runtimeID
		self.chipType = chipType
		self.chipVendors = chipVendors
		self.description = description
		self.fuseDesc = fuseDesc
		self.lockbitDesc = lockbitDesc
		self.packages = packages
		self.comment = comment
		self.chipOptions = chipOptions
		self.maintainer = maintainer
		self.broken = broken

		_registerChip(self)

	@classmethod
	def findAll(cls, chipID, allowBroken=False):
		"Find all ChipDescriptions by fuzzy chipID match."
		found = [ chipDesc for chipDesc in getRegisteredChips() if (
			(not chipDesc.broken or allowBroken) and\
			(chipDesc.chipID.lower().find(chipID.lower()) >= 0)
		) ]
		return found

	@classmethod
	def findOne(cls, chipID, allowBroken=False):
		"""Find a chip implementation and return the ChipDescriptor.
		Raise an exception, if chipID is not unique."""
		found = cls.findAll(chipID, allowBroken)
		if not found:
			raise TOPException("Did not find chipID \"%s\"" % chipID)
		if len(found) != 1:
			choices = [ desc.chipID for desc in found ]
			raise TOPException(
				"The chipID \"%s\" is not unique. Choices are: %s" %\
				(chipID, ", ".join(choices)))
		return found[0]

	@classmethod
	def dumpAll(cls, fd, verbose=1, showBroken=True):
		"Dump all supported chips to file fd."
		count = 0
		for chip in getRegisteredChips():
			if chip.broken and not showBroken:
				continue
			if chip.chipType == cls.TYPE_INTERNAL:
				continue
			count = count + 1
			if count >= 2:
				fd.write("\n")
			chip.dump(fd, verbose)

	def dump(self, fd, verbose=1):
		"Dump information about a registered chip to file fd."

		if verbose <= 0:
			fd.write(self.chipID)
			return

		def wrline(prefix, content):
			# Write a formatted feature line
			fd.write("%15s:  %s\n" % (prefix, content))

		banner = ""
		if self.chipVendors:
			banner += ", ".join(self.chipVendors) + "  "
		if self.description:
			banner += self.description
		else:
			banner += self.bitfile
		extraFlags = []
		if not self.maintainer:
			extraFlags.append("Orphaned")
		if self.broken:
			extraFlags.append("Broken implementation")
		if extraFlags:
			banner += "  (%s)" % "; ".join(extraFlags)
		sep = '+' + '-' * (len(banner) + 4) + '+\n'
		fd.write(sep + '|  ' + banner + '  |\n' + sep)

		if verbose >= 1:
			wrline("Chip ID", self.chipID)
		if verbose >= 2:
			bitfile = self.bitfile
			if not bitfile.endswith('.bit'):
				bitfile += '.bit'
			wrline("BIT file", bitfile)
		if verbose >= 1:
			for opt in self.chipOptions:
				wrline("Chip option", str(opt))
		if verbose >= 3 and self.packages:
			for (package, description) in self.packages:
				if description:
					description = "  (" + description + ")"
				wrline("Chip package", package + description)
		if verbose >= 4:
			supportedFeatures = (
				(Chip.SUPPORT_ERASE,		"Full chip erase"),
				(Chip.SUPPORT_SIGREAD,		"Chip signature reading"),
				(Chip.SUPPORT_PROGMEMREAD,	"Program memory reading (flash)"),
				(Chip.SUPPORT_PROGMEMWRITE,	"Program memory writing (flash)"),
				(Chip.SUPPORT_EEPROMREAD,	"(E)EPROM memory reading"),
				(Chip.SUPPORT_EEPROMWRITE,	"(E)EPROM memory writing"),
				(Chip.SUPPORT_FUSEREAD,		"Fuse bits reading"),
				(Chip.SUPPORT_FUSEWRITE,	"Fuse bits writing"),
				(Chip.SUPPORT_LOCKREAD,		"Lock bits reading"),
				(Chip.SUPPORT_LOCKWRITE,	"Lock bits writing"),
				(Chip.SUPPORT_RAMREAD,		"RAM reading"),
				(Chip.SUPPORT_RAMWRITE,		"RAM writing"),
				(Chip.SUPPORT_TEST,		"Unit-testing"),
				(Chip.SUPPORT_UILMREAD,		"User ID Location reading"),
				(Chip.SUPPORT_UILWRITE,		"User ID Location writing"),
			)
			supportFlags = self.chipImplClass.getSupportFlags()
			for (flag, description) in supportedFeatures:
				if flag & supportFlags:
					wrline("Support for", description)
		if verbose >= 2 and self.comment:
			wrline("Comment", self.comment)
		if verbose >= 3:
			maintainer = self.maintainer
			if not maintainer:
				maintainer = "NONE"
			wrline("Maintainer", maintainer)

	def getChipOption(self, name):
		"Get a ChipOption by case insensitive 'name'."
		name = name.lower()
		for opt in self.chipOptions:
			if opt.name.lower() == name:
				return opt
		return None
bues.ch cgit interface