Getting Started with myStorm BlackIce
myStorm BlackIce is a unique combination of low power FPGA and ARM microcontroller designed and manufactured specifically to bring affordable FPGA open source hardware and software to Hobbyists, Makers and Students.
Working in conjunction with Clifford Wolf’s innovative open source FPGA development toolchain, known as “Project IceStorm” it allows new digital designs to be written in verilog, synthesised and programmed into the FPGA.
The features found on BlackIce offer the user access to the widest variety of devices and expansion interfaces including PMODs, microSD, SRAM, LEDs switches and buttons.
External circuits connect via the PMOD connectors – and these are available from a variety of sources or for the experienced hobbyist some of these expansion devices may be created at home – using readily available hardware.
Few FPGA development boards feature a powerful 32-bit ARM microcontroller on board , such as the STM32L433 – but it was found at the development stage of the myStorm project that including a microcontroller greatly widened the scope for experimentation, and provided a powerful, versatile, support chip to the FPGA.
The STM32 provides the programming interface for the FPGA, so that it may be programmed over USB using little more than a serial terminal program.
For Windows Users – TeraTerm is Recommended.
For MAC OS X Users – CoolTerm
For Linux Users – see notes below
Alternatively the FPGA may be programmed via a Raspberry Pi – particularly useful if the Raspberry Pi is being used to host the FPGA development toolchain.
Project IceStorm was written by Clifford Wolf with contributions from others – and it is used to program a range of FPGAs entirely using open source software. It is a viable alternative to the proprietary toolchains provided by FPGA vendors which often consume tens of gigabytes on the hard drive. Project IceStorm is tiny by comparison.
Project IceStorm aims at reverse engineering and documenting the bitstream format of Lattice iCE40 FPGAs and providing simple tools for analyzing and creating bitstream files. The IceStorm flow (Yosys, Arachne-pnr, and IceStorm) is a fully open source Verilog-to-Bitstream flow for iCE40 FPGAs.
The focus of the project is on the iCE40 LP/HX 1K/4K/8K chips. BlackIce uses the iCE40HX4K-TQ144 part
The typical workflow involved in creating a working FPGA design
- Create your design using the verilog hardware description language using a text editor.
- Submit the verilog file (eg design.v) to the YoSys Logic Synthesiser
- Invoke the Arachne Place and Route to act on the YoSys output file
- Use the IceStorm toolchain (icepack, icebox, iceprog, icetime, chip databases) to create the bitstream file
- Program the Bitstream file into the FPGA
Whilst this set of operations may seem quite complex – it can be automated either from the command line, or by using the APIO IDE – which is a cross-platform IDE tailored to the requirements of FPGA design projects.
The STM32L433 Microcontroller
On the left hand side of the BlackIce pcb is the 64 pin microcontroller which acts as the support device for the FPGA – primarily handling the programming function.
The STM32L433 has 256K of flash memory and 64K of SRAM clocked at a maximum of 80MHz. It is a powerful microcontroller in its own right – similar in capability to an Arduino Due.
20 of its GPIO lines are brought out to Arduino style headers for maximum flexibility and access to analogue and digital interfaces.
The STM32 may be programmed with Arduino (1.8.3 or later) or using the mbed online compiler. Forth enthusiasts can use Mecrisp Ice V0.9 – which has been specifically tailored to support the STM32 and the ICE40 FPGA.
The STM32 is used to buffer the bitstream file – that is the binary format file that is used to program the FPGA with its logical design. This bitstream file is created using an open source toolchain called Project IceStorm.
Why a Microcontroller?
The STM32L433 microcontroller is a powerful 32-bit ARM Cortex M4 device clocked at 80MHz and offering 100DMIPS. It is however one of the ultra-low power series – so perfectly complements the iCE40 – which is also a low power part.
Every FPGA needs some supporting hardware to allow the Bitstream file to be programmed into it’s internal RAM – and this is very often done by an FTDI device – the FT2232. However this FT2232 is an expensive part, costing about $4.50, and it still needs a $0.30 Flash memory to hold the bitfile. Once the FT2232 has programmed the Flash chip, it can then serve as a UART to USB interface for the FPGA.
When we designed myStorm, we decided that the cost of the FTDI device was prohibitive – and we could get a lot more value from the board by spending that part of the budget on a high spec microcontroller – and using that to provide the FPGA programming function. When not actually in programming mode – it can be used to host the User’s application – which can be written in a variety of languages. The result is that you get a general purpose microcontroller development board, with access to 20 lines of digital and analogue I/O – capable of working with some of the currently most popular microcontroller environments.
The microcontroller adds support and versatility to the FPGA, and for some designs the combination of FPGA and ARM will give rise to some unique projects.
The mcu and the FPGA are connected via a Quad SPI bus – capable of running at 60MHz – or 240Mbit/s.
The mcu provides analogue peripherals including a multi-channel 5MSPs 12bit ADC and two 12-bit DAC channels
BlackIce offers features not found in other comparably priced FPGA boards
More PMODS – a total of 6 double and 2 single PMODS = 56 GPIO lines appear on PMODS including differential LVDS lines
For compatibility – further GPIOs have been routed to an Olimex expansion board header
STM32 ARM Cortex co-processor acts as a complete support system for the FPGA – offering a convenient means of programming the FPGA
The STM32 mcu adds 20off 5V tolerant analogue and digital I/O routed to Arduino style headers – including 6 analogue to digital converter inputs and 2 DAC outputs with 12 bit resolution
STM32 can be used as a slave set of standard peripherals to the outside world – including timers, ADC DAC, SPI, I2C and USB
It can be programmed using STM32Duino, mBed Nucleo, MeCrisp Forth.
BlackIce includes a 256Kx16 SRAM closely coupled to the FPGA
microSD card socket on underside of pcb – which may be accessed either by the FPGA or ARM mcu
Using APIO to manage the ToolChain and Development Process
The APIO package is a plug-in for the open source Atom Editor environment. It was written specifically to manage projects involving the Project Icestorm toolchain and Lattice ICE40 FPGAs.
Project Icestorm consists of several stages which are conveniently managed by the APIO IDE which is a derivative of PlatformIO – specifically tailored to meet the needs of the Project IceStorm toolchain. APIO runs as a module within the Atom Editor Environment.
The advantage of using an IDE such as APIO, is that it works across all platforms, and provides a convenient way of managing the toolchain and the various modules (files) that make up the design project.
The design is coded in verilog, and it’s then just a case of building the project.
This invokes the YoSys “Logic Synthesiser” and the Arachne “Place and Route” tools. It then takes the p&r file and converts it into a binary “Bitfile” which is used to program the FPGA.
On BlackIce, an STM32L433 ARM M4 Cortex microcontroller is used to manage the programming of the ICE40 FPGA.
The STM32 device runs an application firmware called “Iceboot” – and this allows the binary bitstream file to be loaded via the STM32 and then into the FPGA.
This is done via the native USB device port on the STM32 microcontroller using a terminal program such as Teraterm, using it’s “Send File” option from the File menu tab. Ensure that the Binary option is checked on the file selection dialogue box. FPGA loading takes only about 2 or 3 seconds.
Programming the STM32
In our application the STM32 runs the programming firmware “Iceboot”. However it can be programmed to permanently retain the FPGA bitstream image – so that this is automatically loaded on power-up. This may be useful for demonstration purposes where you want the FPGA image to be non-volatile.
Additionally, the STM32 may be programmed with application firmware, provided that this does not interfere with the FPGA loading mechanism.
20 lines of GPIO, including six ADC channels are brought out to Arduino-style expansion connectors, and these are available for User experimentation.
The STM32 is readily programmed using mbed – as it can be made to look like a Nucleo device – using a ST-Link to program it. Later versions of the Arduino IDE now support the M4 Cortex microcontroller – so this may also be used.
Alternatively it can be put into DFU (Device Firmware Upgrade) mode by removing the jumper link connected across the 7th and 8th pin of the right hand row of header pins. Reflashing the firmware using DFU is an advanced topic, and is covered in the Appendix.
These headers allow access to many of the interfaces on the microcontroller including ADC inputs, DAC outputs, SPI, I2C and UART interfaces and timer inputs and outputs. They also access the four “slide switch” inputs that connect to both FPGA and ARM.
The headers run east-west across the centre of the board, and break out many of the ARM microcontroller GPIO signal to a set of connectors that are compatible with Arduino shields. Note that whist these GPIO lines are 5V tolerant – the rest of the board is 3V3 only – so extreme care should be exercised when working with mixed supply rail designs.
The Arduino Shield headers can be used to access up to 20 digital lines and 6 analogue lines.
50mm x 50mm square pcbs may be conveniently mounted – or an extended shield 60mm x 50mm will pick up all 14 LVDS pairs from the Olimex connector. Care should be taken however because the FPGA lines are not 5V tolerant.
There are to user push button switches which connect to both the microcontroller and the FPGA. These are useful for when a logic design requires momentary intervention.
They are connected to pins PC8 and PC9 of the microcontroller and pins 63 and 64 of the FPGA.
In addition to the push switches on the left, there are four DIP slide switches arranged in two banks of two. These also connect to both the mcu and the FPGA and are also exposed to the outside world via pins on the “Digital 3” connector of the Arduino Headers. They are useful for setting up a mode of operation or connecting to external stimuli.
To the right of the mode switches is a Reset Button which provides a momentary active low reset signal to the microcontroller. This is independent of the high going reset signal that the microcontroller sends to the FPGA at the time of programming.
System connector – sometimes called the “Pi Header”
This is a 2 x13 male header on the left hand edge of the pcb which carries certain signals that allow the FPGA to be programmed from an external device such as a Raspberry Pi. It has a mix of programming pins, control pins and power.
The UART RX and TX signal lines from the FPGA also appear on pins – compatible with the position of the corresponding UART pins on the Raspberry Pi expansion header. Full details of these signals are in the appendix.
Programming Jumper Link.
This is a 2.54mm jumper link which normally bridges across pins 14 and 16 of the system connector. When removed, it forces the microcontroller into DFU boot mode (Device Firmware Upgrade), which allows it to be programmed with new system firmware. Occasionally there may be a firmware upgrade posted in the myStorm repository to provide new features.
The microcontroller may additionally be programmed using a low cost “ST Link” – a small system programming device – which may be sourced cheaply from ebay. This plugs into the programming pins of the system header.
For normal operation, the jumper link must remain across pins 14 and 16.
These are an industry standard interface connector originally devised by Digilent – a major manufacturer of FPGA development boards.
They come in 6 pin or 12 pin (2 rows of 6 pin) right angled female headers, organised on a specific pitch spacing between connectors.
The connect directly to the FPGA GPIO pins and also carry 3V3 and 0V power. Small external circuit boards, carrying a variety of expansion circuitry or devices may be plugged directly into these headers – picking up 4 I/O pins for a single PMOD, and 8 I/O pins on a double PMOD.
On BlackIce there are two single PMOD connectors and 6 double PMOD connectors. The double PMODs on the right hand edge of the pcb carry the fast LVDS (low voltage differential signalling) pairs of signals – and these may be used for driving the most demanding of high speed hardware.
A total of 56 GPIO lines (including 14 pairs of LVDS lines) are brought out via the PMOD connectors.
There are a whole range of third party PMODs available from a variety of suppliers – such as ADCs, 7 segment displays, audio codecs etc, etc. See here for further information plus a selection of what is available: http://store.digilentinc.com/pmod-modules/
The small size of PMOD circuit boards makes them a convenient size for home construction – taking advantage of low cost pcb manufacturing services.
Olimex Expansion Connector
This is a 2 x 17 2.54mm connector that accesses 28 of the FPGA GPIO signals and is compatible with the range of expansion modules supplied by Olimex. These low cost modules include ADC, DAC, VGA & PS/2, and buffered digital I/O.
To take advantage of this – a 2 x 17 pin male header should be fitted in this position, or a 2×17 right angled box header fitted from the underside of the board. More details in the appendix.
On the rear of the pcb is a microSD card socket which may be accessed from the FPGA or the microcontroller.
Also on the rear of the pcb is a 256Kx16 fast (10nS) asynchronous SRAM – directly connected and closely coupled to the FPGA. This can be used in FPGA designs where additional external storage is required.
BlackIce is provides with a 100MHz oscillator module from which internal clock signals for the FPGA may be derived via the internal PLL (phase locked loop) module.
A small 2 way multiplexer chip allows selection between external programming of the FPGA from the system connector, or onboard programming from the ARM device. When onboard programming is selected it routes the output of the FPGA signals P52, P53,P54 and P55 to the SPI bus of the microcontroller, whilst ordinarily these are used for driving the LEDs.
There are four coloured LEDs available to the user Blue, Green, Amber and Red. These can be used to indicate certain status within the FPGA, or to create for example a traffic light display.
An additional STATUS LED is connected to port PC13 of the microcontroller – and can be used for user purposes if the user is developing code for the microcontroller using Arduino, mbed or similar.
A further red LED indicates that the FPGA programming has been DONE.
The power white LED shows when 5V power is connected.
Powering the Unit
The board may be powered from either microUSB socket or from the 5V power and 0V ground pins on the 2x13way connector.
There are two microUSB connectors:
This one closest to the ARM chip, just below the 2×13 pin system connector is the direct USB connection to the STM32 microcontroller – and is used primarily for sending the programming bitfile to the mcu.
The lower of the two microUSB sockets connects to a USB-UART converter IC, and is used to communicate serially with the FPGA – assuming that your logic design contains a suitable UART module. It may also be used to convey serial data from the ARM mictocontroller, and on first power-up or following a reset it sends the message showing the firmware revision. The firmware running on STM32 connects to this com port at 115,200 baud.
Sending a Bitstream file to the BlackIce Board
There are two USB sockets:
- Programming Port
The one closer to the middle of the board is connected to the USB interface on the microcontroller – and if you plug into this one – it will appear as a virtual com port, capable of running at more than 1 Mbit/second.
This is the one that is primarily used to transfer the large bitstream file from the laptop, through the microcontroller and into the FPGA – very quickly – in a couple of seconds.
After you have sent the bitstream file and it is correctly loaded – the message should then say
Config done Waiting for UART or USB serial
2. UART Port
The microUSB port nearer the corner of the board is connected via a CH340 USB converter to the UART lines of both the microcontroller and the FPGA.
This port is normally used for getting serial input/output from the FPGA – provided that your logic design included a suitable UART connected to the correct pins.
However, at start-up or following a reset of the STM32 it is used to send a start-up message. Following this message, the STM32 switches it’s Tx line to a high impedance input – allowing the FPGA UART access to the com port adaptor.
If you plug into the lower port – set up a 115,200 baud terminal and press the reset button (top right) you should get this message on the terminal screen
Mystorm Version 0.3 Setup Done
Note that the version is now 0.3 – you may previously have been using version 0.2
This is an alternative programming method that uses “Device Firmware Upgrade” – which is a factory built in bootloader within the STM32 microcontroller. DFU is used for 2 specific purposes:
- To put new firmware onto the STM32
- To load an image of the FPGA design into the flash memory – so it loads this on power-up.
Putting new firmware on the STM32 is covered in Appendix 1.
The other thing to note is that you must keep the jumper link fitted across pins 14 and 16 of the “system” connector. This is only removed when you want to update the firmware that runs on the microcontroller.
The myStorm BlackIce boards are now available in production quantities – and priced as follows:
For Customers in UK £40 + £2 postage
For Customers in EU 45 Euros + 4 Euros shipping
For Customers in US $52.50 + $7.00 shipping
For world wide customers – please contact me and ask about shipping costs.
You can PayPal me at ken dot boak at gmail dot com to place an order or discuss volume discounts.
How to Update the STM32 Firmware using DFU Mode
Unplug blue jumper on pin7&8.
Plug USB cable into socket closest to ARM chip.
Use lsusb to find the device:
lsusb Bus 001 Device 026: ID 0483:df11 STMicroelectronics STM Device in DFU Mode
Use dfu-util (sudo apt-get install dfu-util) to list DFUs:
sudo dfu-util -d 0483:df11 -l dfu-util 0.5 (C) 2005-2008 by Weston Schmidt, Harald Welte and OpenMoko Inc. (C) 2010-2011 Tormod Volden (DfuSe support) This program is Free Software and has ABSOLUTELY NO WARRANTY dfu-util does currently only support DFU version 1.0 Filter on vendor = 0x0483 product = 0xdf11 Found Runtime: [05ac:828f] devnum=0, cfg=1, intf=3, alt=0, name="UNDEFINED" Found DFU: [0483:df11] devnum=0, cfg=1, intf=0, alt=0, name="@Internal Flash /0x08000000/0128*0002Kg" Found DFU: [0483:df11] devnum=0, cfg=1, intf=0, alt=1, name="@Option Bytes /0x1FFF7800/01*040 e" Found DFU: [0483:df11] devnum=0, cfg=1, intf=0, alt=2, name="@OTP Memory /0x1FFF7000/01*0001Ke" Found DFU: [0483:df11] devnum=0, cfg=1, intf=0, alt=3, name="@Device Feature/0xFFFF0000/01*004 e"
We want the internal flash (alt=0), so now with the iceboot.dfu:
sudo dfu-util -d 0483:df11 -D ~/Downloads/iceboot.dfu --alt 0 dfu-util 0.5 (C) 2005-2008 by Weston Schmidt, Harald Welte and OpenMoko Inc. (C) 2010-2011 Tormod Volden (DfuSe support) This program is Free Software and has ABSOLUTELY NO WARRANTY dfu-util does currently only support DFU version 1.0 Filter on vendor = 0x0483 product = 0xdf11 Opening DFU USB device... ID 0483:df11 Run-time device DFU version 011a Found DFU: [0483:df11] devnum=0, cfg=1, intf=0, alt=0, name="@Internal Flash /0x08000000/0128*0002Kg" Claiming USB DFU Interface... Setting Alternate Setting #0 ... Determining device status: state = dfuIDLE, status = 0 dfuIDLE, continuing DFU mode device DFU version 011a Device returned transfer size 2048 Dfu suffix version 11a Warning: File product ID 0000 does not match device df11 DfuSe interface name: "Internal Flash " file contains 1 DFU images parsing DFU image 1 image for alternate setting 0, (1 elements, total size = 22744) parsing element 1, address = 0x08000000, size = 22736 done parsing DfuSe file
Then unplug usb, put jumper back, plug into other USB socket and check dmesg:
[108129.748055] ch341 1-188.8.131.52.3:1.0: ch341-uart converter detected [108129.749285] usb 1-184.108.40.206.3: ch341-uart converter now attached to ttyUSB0
Check serial output:
miniterm /dev/ttyUSB0 115200 --- Miniterm on /dev/ttyUSB0 115200,8,N,1 --- --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
Press reset button:
Mystorm version 0.2 Setup done Waiting for UART
Now you should be able to flash your mystorm like this:
cat chip.bin > /dev/ttyUSB0
(takes about 10 seconds).
STM32 GPIO Pin Out