├── .gitignore
├── README.md
├── iCEburn
    ├── __init__.py
    ├── __main__.py
    ├── libiceblink.py
    └── regtool.py
└── setup.py


/.gitignore:
--------------------------------------------------------------------------------
1 | __pycache__
2 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Lattice iCEBlink40 Programming Tool
 2 | 
 3 | The Lattice iCEBlink40 is a low-cost FPGA board (currently $50 cad) supporting the iCE40 LP/HX families. While the iCEcube programming software on linux supports the chips, it doesn't ship with a port of iceutil.exe to program the board itself. This is an open-source tool, licensed under GPL2, to allow for programming of the FPGA board from linux. 
 4 | 
 5 | This script has only been tested by the author with the iCEblink40-LP1K board, with the M25P10VP flash. Other users have reported that it works with the HX1K flavour boards.
 6 | 
 7 | This tool was created from black-box inspection of the USB datastream between a VM running iceutil and the iCEblink40-LP1K evaluation board. No binary analysis, binary reverse engineering or disassembly was used during the creation of this tool; all information in this file was derived from black-box analysis.
 8 | 
 9 | The iCEBlink boards only support programming of the flash memory used to boot the FPGA. Direct SPI programming of the FPGA does not appear to be possible.
10 | 
11 | # Requirements:
12 | 
13 | - python 3 or newer
14 | - pyusb 1.0 or newer
15 | 
16 | # Usage 
17 | 
18 | ## iCEburn.py
19 | 
20 | The main flash programming tool is iCEburn.py. It supports two operation flags, `-e` for erase, and `-w` for write. The most common usage is:
21 | 
22 | 
23 | `./iCEburn.py -ew path\_to\_build.bin`
24 | 
25 | 
26 | ## regtool.py
27 | 
28 | Regtool is an example test script to poke at registers via the FPGA data link. The argument
29 | 
30 |     -r 0xAB
31 | 
32 | will do a read of register 0xAB and print the result to the console. The argument
33 | 
34 |     -w 0xAB:0xCD
35 |  
36 | will write register 0xAB with value and print the result to the console. With the stock FPGA firmware
37 |  
38 |     ./regtool.py -w 5:0x48
39 | 
40 | will stop the scrolling pattern and fix LED3 on.
41 | 
42 | Regtool is primarily intended as an example of API usage, and not as a production grade tool.
43 | 
44 | 
45 | # Bugs
46 | 
47 | - If using old versions of pyUSB, you may get an error:
48 | 
49 |     AttributeError: "'NoneType' object has no attribute 'libusb_exit'"
50 | 
51 | This is a bug in pyusb.
52 | 
53 | 
54 | # TODO
55 | 
56 | - Add additional flash devices
57 | 
58 | 


--------------------------------------------------------------------------------
/iCEburn/__init__.py:
--------------------------------------------------------------------------------
1 | name = "iCEburn"
2 | 


--------------------------------------------------------------------------------
/iCEburn/__main__.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/python3
 2 | import argparse
 3 | from iCEburn.libiceblink import ICE40Board, M25P10
 4 | 
 5 | def main():
 6 |     ap = argparse.ArgumentParser()
 7 |     ap.add_argument("-e", "--erase", action="store_true")
 8 |     ap.add_argument("-v", "--verbose", action="store_true")
 9 |     ap.add_argument("-w", "--write", type=argparse.FileType("rb"))
10 |     args = ap.parse_args()
11 | 
12 |     board = ICE40Board()
13 | 
14 |     if args.verbose:
15 |         print("Found iCE40 board serial: %s" % board.get_serial())
16 | 
17 | 
18 |     sp = board.get_spi_port(0)
19 | 
20 |     with board.get_gpio() as gpio:
21 |         # Force the FPGA into reset so we may drive the IOs
22 |         gpio.ice40SetReset(True)
23 | 
24 |         with board.get_spi_port(0) as sp:
25 |             sp.setSpeed(50000000)
26 |             sp.setMode()
27 | 
28 |             flash = M25P10(sp.io)
29 | 
30 |             flash.wakeup()
31 |             
32 |             # Verify that we're talking to the part we think we are
33 |             assert flash.getID() == b'\x20\x20\x11'
34 | 
35 |             # Now, do the actions
36 |             if args.erase:
37 |                 if args.verbose:
38 |                     print("Erasing flash...")
39 |                 flash.chipErase()
40 |                 if args.verbose:
41 |                     print("")
42 | 
43 |             if args.write:
44 |                 data = args.write.read()
45 | 
46 |                 if args.verbose:
47 |                     print("Writing image...")
48 | 
49 |                 for addr in range(0, len(data), 256):
50 |                     buf = data[addr:addr+256]
51 |                     flash.pageProgram(addr, buf)
52 | 
53 |                 if args.verbose:
54 |                     print("Verifying written image...")
55 |                 # Now verify
56 |                 buf = flash.read(0, len(data))
57 |                 assert len(buf) == len(data)
58 |             
59 |                 nvfailures = 0
60 |                 for i,(a,b) in enumerate(zip(buf, data)):
61 |                     if a!=b:
62 |                         print ("verification failure at %06x: %02x != %02x" %
63 |                                (i,a,b))
64 |                         nvfailures += 1
65 | 
66 |                     if nvfailures == 5:
67 |                         print("Too many verification failures, bailing")
68 |                         break
69 | 
70 |         # Release the FPGA reset
71 |         gpio.ice40SetReset(False)
72 | 
73 | 
74 | if __name__ == "__main__":
75 |     main()
76 | 


--------------------------------------------------------------------------------
/iCEburn/libiceblink.py:
--------------------------------------------------------------------------------
  1 | import usb.core
  2 | import usb.util
  3 | import array
  4 | import struct
  5 | import binascii
  6 | import time
  7 | 
  8 | class ProtocolError(Exception):
  9 |     pass
 10 | 
 11 | class SPIProtocolError(Exception):
 12 |     def __init__(self, cmd, rescode):
 13 |         lut = {
 14 |             3: "Resource in use",
 15 |             4: "Resource not opened",
 16 |             12: "Invalid enum"
 17 |         }
 18 |         if rescode in lut:
 19 |             err = lut[rescode]
 20 |         else:
 21 |             err = "error code %d" % rescode
 22 | 
 23 |         ProtocolError.__init__(self, "Command %s failed with error: %s" %( cmd,
 24 |                                err))
 25 | 
 26 | class M25P10(object):
 27 |     STAT_BUSY = 0x1
 28 |     STAT_WEL = 0x2
 29 | 
 30 |     CMD_GET_STATUS = 0x05
 31 |     CMD_WRITE_ENABLE = 0x6
 32 |     CMD_READ_ID = 0x9F
 33 |     CMD_WAKEUP = 0xAB
 34 |     CMD_CHIP_ERASE = 0xC7
 35 |     CMD_PAGE_PROGRAM = 0x02
 36 |     CMD_FAST_READ = 0xB
 37 | 
 38 |     def __init__(self, iofn):
 39 |         self.io = iofn
 40 | 
 41 |     def wakeup(self):
 42 |         self.io([self.CMD_WAKEUP])
 43 | 
 44 |     def setWritable(self):
 45 |         self.io([self.CMD_WRITE_ENABLE])
 46 | 
 47 |     def chipErase(self):
 48 |         self.setWritable()
 49 |         self.io([self.CMD_CHIP_ERASE])
 50 |         self.waitDone()
 51 | 
 52 |     def read(self, addr, size):
 53 |         return self.io([self.CMD_FAST_READ, (addr>>16) & 0xFF, (addr>>8)&0xFF, addr &
 54 |                         0xFF, 0x00], size+5)[5:]
 55 |     def pageProgram(self, addr, buf):
 56 |         self.setWritable()
 57 |         assert len(buf) <= 256
 58 |         assert addr & 0xFF == 0
 59 | 
 60 |         self.io([self.CMD_PAGE_PROGRAM, (addr>>16) & 0xFF, (addr>>8)&0xFF, addr &
 61 |                  0xFF] + list(buf))
 62 |         self.waitDone()
 63 | 
 64 |     def waitDone(self):
 65 |         while self.getStatus() & self.STAT_BUSY:
 66 |             pass
 67 | 
 68 |     def getStatus(self):
 69 |         return self.io([self.CMD_GET_STATUS],2)[1]
 70 | 
 71 |     def getID(self):
 72 |         return self.io([self.CMD_READ_ID],4)[1:]
 73 | 
 74 | 
 75 | class ICE40Board(object):
 76 | 
 77 |     CMD_GET_BOARD_TYPE = 0xE2
 78 |     CMD_GET_BOARD_SERIAL = 0xE4
 79 | 
 80 |     class __ICE40BoardComm(object):
 81 |         def __init__(self, dev):
 82 |             self.__is_open = False
 83 |             self.dev = dev
 84 | 
 85 |         def __enter__(self):
 86 |             self.open()
 87 |             return self
 88 |         
 89 |         def __exit__(self, type, err, traceback):
 90 |             self.__cleanup()
 91 | 
 92 |         def __del__(self):
 93 |             self.__cleanup()
 94 | 
 95 |         def __cleanup(self):
 96 |             if self.__is_open:
 97 |                 self.close()
 98 | 
 99 |         def open(self):
100 |             assert not self.__is_open
101 |             self.dev.checked_cmd(0x04, 0x00, "bcommopen", [0x00], noret=True)
102 |             self.__is_open = True
103 | 
104 |         def close(self):
105 |             assert self.__is_open
106 |             self.dev.checked_cmd(0x04, 0x01, "bcommclose", [0x00], noret=True,
107 |                                  )
108 |             self.__is_open = False
109 | 
110 |         def __check_counts(self, status, resb, wr, rd):
111 |             if status & 0x80:
112 |                 wb = struct.unpack('<L', resb[:4])[0]
113 |                 resb = resb[4:]
114 |                 #print (wb, write_byte_count)
115 |                 assert wb == wr
116 |                 
117 |             if status & 0x40:
118 |                 rb = struct.unpack('<L', resb[:4])[0]
119 |                 resb = resb[4:]
120 |                 assert rb == rd
121 | 
122 |         def readReg(self, regno):
123 |             self.dev.checked_cmd(0x04, 0x05, "bcommsetval", [0x00, regno, 
124 |                                                              0x01, 0x00, 0x00, 0x0])
125 |             res = self.dev.ep_datain.read(1)
126 |             status, pl = self.dev.cmd(0x04, 0x85, [0x00])
127 |             self.__check_counts(status, pl, 0, 1)
128 |             return res[0]
129 | 
130 |         def writeReg(self, regno, value):
131 |             self.dev.checked_cmd(0x04, 0x04, "bcommsetval", [0x00, regno,
132 |                                                              0x01, 0x00, 0x00, 0x0])
133 |             self.dev.ep_dataout.write([value])
134 |             status, pl = self.dev.cmd(0x04, 0x85, [0x00])
135 |             self.__check_counts(status, pl, 1, 0)
136 | 
137 |         def readMulti(self, addrs):
138 |             pass
139 | 
140 |         def writeMulti(self, addrvals):
141 |             pass
142 | 
143 |     class __ICE40GPIO(object):
144 |         def __init__(self, dev):
145 |             self.__is_open = False
146 |             self.dev = dev
147 | 
148 |         def __enter__(self):
149 |             self.open()
150 |             return self
151 | 
152 |         def __exit__(self, type, err, traceback):
153 |             self.__cleanup()
154 | 
155 |         def __del__(self):
156 |             self.__cleanup()
157 | 
158 |         def open(self):
159 |             assert not self.__is_open
160 |             # Some kind of open
161 |             self.dev.checked_cmd(0x03, 0x00, "gpioopen", [0x00], noret=True)
162 |             self.__is_open = True
163 |             
164 |         def close(self):
165 |             assert self.__is_open
166 |             self.dev.checked_cmd(0x03, 0x01, "gpioclose", 0x00)
167 |             self.__is_open = False
168 | 
169 |         def __cleanup(self):
170 |             if self.__is_open:
171 |                 self.close()
172 | 
173 |         def __set_dir(self, direction):
174 |             self.dev.checked_cmd(0x03, 0x04, "0304", [0x00, direction, 0x00,
175 |                                                       0x00, 0x00])
176 | 
177 |         def __set_value(self, value):
178 |             self.dev.checked_cmd(0x03, 0x06, "0306", [0x00, value, 0x00, 0x00,
179 |                                                   0x00],noret=True)
180 | 
181 |         def ice40SetReset(self, assert_reset):
182 |             if assert_reset:
183 |                 self.__set_dir(1)
184 |                 self.__set_value(0)
185 |             else:
186 |                 self.__set_dir(0)
187 | 
188 | 
189 |     class __ICE40SPIPort(object):
190 |         def __init__(self, dev, portno):
191 |             self.dev = dev
192 |             self.__portno = portno
193 |             assert portno == 0x00
194 |             self.__is_open = False
195 | 
196 |         def __enter__(self):
197 |             self.open()
198 |             return self
199 | 
200 |         def __exit__(self, type, exc, traceback):
201 |             self.__cleanup()
202 | 
203 |         def __del__(self):
204 |             self.__cleanup()
205 | 
206 |         def __cleanup(self):
207 |             if self.__is_open:
208 |                 self.close()
209 | 
210 |         def io(self, write_bytes, read_byte_count=0):
211 |             assert self.__is_open
212 |             write_bytes = list(write_bytes)
213 | 
214 |             # Pad write bytes to include 00's for readback
215 |             if len(write_bytes) < read_byte_count:
216 |                 write_bytes.extend([0] * (read_byte_count - len(write_bytes)))
217 | 
218 |             write_byte_count = len(write_bytes)
219 |             read_bytes = []
220 | 
221 |             # probably assert nCS
222 |             self.dev.checked_cmd(0x06, 0x06, "SPIStart", [0x00, 0x00])
223 | 
224 | 
225 |             # Start IO txn
226 |             self.dev.checked_cmd(0x06, 0x07, "SPIIOStart", 
227 | 
228 |                  # the meaning of the first 3 bytes is unknown
229 |                  struct.pack("<BBBBL", 0x00, 0x00, 0x00, 
230 |                              0x01 if read_byte_count else 0x00,
231 |                              write_byte_count),noret=True)
232 | 
233 |             # Do the IO
234 |             while write_bytes or len(read_bytes) < read_byte_count:
235 |                 if write_bytes:
236 |                     self.dev.ep_dataout.write(write_bytes[:64])
237 |                     write_bytes = write_bytes[64:]
238 | 
239 |                 if read_byte_count:
240 |                     to_read = min(64, read_byte_count) 
241 |                     read_bytes.extend(self.dev.ep_datain.read(to_read))
242 | 
243 | 
244 | 
245 |             # End IO txn
246 |             status, resb =self.dev.cmd(0x06, 0x87,[0x00])
247 |            
248 |             # status & 0x80 indicates presence of write size
249 |             # status & 0x40 indicates presence of read size
250 |             # validate values
251 |             if status & 0x80:
252 |                 wb = struct.unpack('<L', resb[:4])[0]
253 |                 resb = resb[4:]
254 |                 #print (wb, write_byte_count)
255 |                 assert wb == write_byte_count
256 |                 
257 |             if status & 0x40:
258 |                 rb = struct.unpack('<L', resb[:4])[0]
259 |                 resb = resb[4:]
260 |                 assert rb == read_byte_count
261 | 
262 |             # Clear CS
263 |             self.dev.checked_cmd(0x06, 0x06, "0606", [0x00, 0x01])
264 | 
265 |             return bytes(read_bytes)
266 | 
267 |         def open(self):
268 |             assert not self.__is_open
269 |             pl = self.dev.checked_cmd(0x06, 0x00, "SPIOpen", [self.__portno])
270 |             assert len(pl) == 0
271 |             self.__is_open = True
272 | 
273 |         def close(self):
274 |             pl = self.dev.checked_cmd(0x06, 0x01, "SPIClose", [self.__portno])
275 |             assert len(pl) == 0
276 |             self.__is_open = False
277 | 
278 |         def setMode(self):
279 |             """May be mode-setting. [0,2] causes bits to be returned shifted right
280 |             one"""
281 |             assert self.__is_open
282 |             pl = self.dev.checked_cmd(0x06, 0x05, "SpiMode", [0,0])
283 |             assert len(pl) == 0
284 | 
285 |         def setSpeed(self, speed):
286 |             """ sets the desired speed for the SPI interface. Returns actual speed
287 |             set"""
288 |             pl = self.dev.checked_cmd(0x06, 0x03, "SPISpeed", b'\x00' +
289 |                                   struct.pack("<L", speed))
290 |             assert self.__is_open
291 |             return (struct.unpack("<L",pl),)
292 | 
293 | 
294 |     def __init__(self):
295 |         # find our self.device
296 |         self.dev = usb.core.find(idVendor=0x1443, idProduct=0x0007)
297 |         if self.dev is None:
298 |             raise ValueError('Device not found')
299 | 
300 |         self.dev.reset()
301 |         self.dev.set_configuration()
302 |         
303 |         # get an endpoint instance
304 |         cfg = self.dev.get_active_configuration()
305 |         intf = usb.util.find_descriptor(cfg)
306 | 
307 |         # Allocate and verify all the endpoints used for comms
308 |         self.ep_cmdout  = usb.util.find_descriptor(intf, bEndpointAddress = 1)
309 |         self.ep_cmdin   = usb.util.find_descriptor(intf, bEndpointAddress = 0x82)
310 |         self.ep_dataout = usb.util.find_descriptor(intf, bEndpointAddress = 3)
311 |         self.ep_datain  = usb.util.find_descriptor(intf, bEndpointAddress = 0x84)
312 | 
313 |         assert self.ep_cmdout is not None
314 |         assert self.ep_cmdin is not None
315 |         assert self.ep_dataout is not None
316 |         assert self.ep_datain is not None
317 | 
318 |         # Make sure we're talking to what we expect
319 |         btype = self.get_board_type()
320 |         assert btype == 'iCE40'
321 | 
322 |     def get_spi_port(self, pn):
323 |         return self.__ICE40SPIPort(self, pn)
324 | 
325 |     def get_gpio(self):
326 |         return self.__ICE40GPIO(self)
327 | 
328 |     def get_board_comm(self):
329 |         return self.__ICE40BoardComm(self)
330 | 
331 |     def ctrl(self, selector, size_or_data, show=False):
332 |         val = self.dev.ctrl_transfer(0xC0 if isinstance(size_or_data, int) else 0x04, 
333 |                           selector, 0x00, 0x00, size_or_data)
334 |         if show and isinstance(val, array.array):
335 |             print("%2x < %s" % (selector, "".join("%02x" % i for i in val)))
336 |         return bytes(val)
337 | 
338 |     def checked_cmd(self, cmd, subcmd, name, payload=[], ressize=16, show=False,
339 |                    noret=False):
340 |         status, respl = self.cmd(cmd, subcmd, payload, ressize, show)
341 |         if status != 0:
342 |             raise SPIProtocolError(name, status)
343 |         if noret:
344 |             assert len(respl) == 0
345 |         return respl
346 | 
347 |     def cmd(self, cmd, subcmd, payload, ressize=16, show=False):
348 |         res = self.cmd_i(
349 |             struct.pack("<BB", cmd, subcmd) + bytes(payload),
350 |             ressize)
351 | 
352 |         status = res[0]
353 |         if show:
354 |             print ("%02x:%02x (%s) < %02x:(%s)" % (cmd, subcmd,
355 |                                               binascii.hexlify(bytes(payload)).decode('ascii'),
356 |                                               status,
357 |                                                    binascii.hexlify(res[1:]).decode('ascii')))
358 |         return status, res[1:]
359 | 
360 |     def cmd_i(self, cmd_bytes, result_size, show=False):
361 |         payload = struct.pack('<B', len(cmd_bytes)) + bytes(cmd_bytes)
362 |         self.ep_cmdout.write(payload)
363 |         res = bytes(self.ep_cmdin.read(result_size))
364 | 
365 |         if show:
366 |             print("%s:%s" % (binascii.hexlify(payload).decode('ascii'),
367 |                              binascii.hexlify(res).decode('ascii')))
368 |         assert res[0] == len(res[1:])
369 |         return res[1:]
370 | 
371 |     def get_board_type(self):
372 |         btype = self.ctrl(0xE2, 16)
373 |         return btype[:btype.index(b'\x00')].decode('ascii')
374 | 
375 |     def get_serial(self):
376 |         return self.ctrl(0xE4, 16).decode('ascii')
377 | 
378 | 


--------------------------------------------------------------------------------
/iCEburn/regtool.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/python3
 2 | 
 3 | import argparse
 4 | from iCEburn.libiceblink import ICE40Board
 5 | 
 6 | def rtype(x):
 7 |     return ('R', int(x, 16))
 8 | 
 9 | def wtype(x):
10 |     return ('W', [int(i,16) for i in x.split(':')])
11 | 
12 | def main():
13 |     ap = argparse.ArgumentParser()
14 |     ap.add_argument("-r", "--read", dest='actions', type=rtype, action='append')
15 |     ap.add_argument("-w", "--write", dest='actions', type=wtype, action='append')
16 |     args = ap.parse_args()
17 | 
18 |     board = ICE40Board()
19 |     with board.get_board_comm() as comm:
20 |         for atype, arg in args.actions:
21 |             if atype == 'R':
22 |                 addr = arg
23 |                 print("READ  %02x: %02x" % (addr, comm.readReg(addr)))
24 |             elif atype == 'W':
25 |                 addr, value = arg
26 |                 print("WRITE %02x: %02x" % (addr, value))
27 |                 comm.writeReg(addr, value)
28 | 
29 | 
30 | if __name__ == "__main__":
31 |     main()
32 | 


--------------------------------------------------------------------------------
/setup.py:
--------------------------------------------------------------------------------
 1 | # -*- coding: utf-8 -*-
 2 | 
 3 | from setuptools import setup, find_packages
 4 | 
 5 | 
 6 | with open("README.md", "r") as fh:
 7 |     long_description = fh.read()
 8 | 
 9 | setup(
10 |     name='iCEburn',
11 |     packages=find_packages(),
12 |     install_requires=['pyusb'],
13 |     python_requires='>3.3',
14 |     version='0.1.1',
15 |     description='Programmer for iCEblink40 boards',
16 | 
17 |     long_description=long_description,
18 |     long_description_content_type="text/markdown",
19 | 
20 |     author='David Carne',
21 |     author_email='davidcarne@gmail.com',
22 |     url='https://github.com/davidcarne/iceBurn',
23 |     keywords=['fpga', 'ice40', 'programmer'],
24 |     license='BSD',
25 |     classifiers=(
26 |         "License :: OSI Approved :: BSD License",
27 |         "Programming Language :: Python :: 3.0",
28 |         "Operating System :: OS Independent",
29 |     ),
30 |     entry_points={
31 |         'console_scripts':[
32 |             'iCEburn = iCEburn.__main__:main',
33 |             'iCEreg = iCEburn.regtool:main'
34 |         ]
35 |     },
36 | )
37 | 
38 | 


--------------------------------------------------------------------------------