FPGA Development on M2 Mac: TinyFPGA with IceStudio

I've traditionally always used Linux VMs to do all of my FPGA works on both Mac and Windows. However, with the recent uptake of ARM-based CPUs in laptops and a major lack of ARM-based support in some FPGA development tools, my interest in finding native Mac FPGA development tools was rekindled.

While there are several Yosys-based projects for open source FPGA development, I recently came across IceStudio. The IceStudio IDE is a very novice-friendly block GUI similar in concept to Vivado's block design for Lattice Semiconductor iCE40-based FPGA development boards. Bonus: it's available on Windows, Linux, and Mac (both ARM and Intel based).

Since I recently purchase an M2 MacBook Air, I figured I'd start a series on FPGA and embedded development on ARM-based Mac OS. I guess this would technically be the second installment in this series as I previously did a write-up on compiling and uploading applications to my Raspberry Pi Pico on my M2 Mac.

While the installation and use of IceStudio is fairly straightforward and self-explanatory for Intel based Macs and Linux machines, I did find some pitfalls with the ARM-based M1/M2 installation that I thought made it worth doing this write-up since I had to build/install IceStudio from source before I was able to get it to work properly. For reference, I am using a 2022 M2 MacBook Air running Ventura 13.4.

Install Dependencies

First things first if you haven't already, you'll need to install the Homebrew Mac OS package manager. This is a must for any developer/engineering work on a Mac in my opinion.

Pull down the source code for Homebrew and run the install script for it using curl:

whitneyknitter@Whitneys-Air ~ % /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After the install script runs successfully, it will print out directions for the commands you need to run to set the necessary environment variables in your system in order to use Homebrew. For me, this looked like the following:

whitneyknitter@Whitneys-Air ~ % echo '# Set PATH, MANPATH, etc., for Homebrew.' >> /Users/whitneyknitter/.zprofile
whitneyknitter@Whitneys-Air ~ % echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/whitneyknitter/.zprofile
whitneyknitter@Whitneys-Air ~ % eval "$(/opt/homebrew/bin/brew shellenv)"

Once the necessary environment variables are set for Homebrew, it's a good idea to test it out using something like the help flag:

whitneyknitter@Whitneys-Air ~ % brew help

Next, install Python through Homebrew, even if you already have Python installed natively. The Python installation through Homebrew is separate from any other installs done not using Homebrew and won't mess with them so no worries.

whitneyknitter@Whitneys-Air ~ % brew install python

After Python, install Node.js using Homebrew:

whitneyknitter@Whitneys-Air ~ % brew install node

Once Node.js is installed, use the npm package manager to install the JavaScript task runner Grunt:

whitneyknitter@Whitneys-Air ~ % sudo npm install -g grunt-cli

Install Icestudio

Download the zipped source code files here for the 0.10 (latest version at the time of writing) and save them to the desired location. I just left mine in my downloads folder, but that's not critical to the functionality of the IceStudio application.

Change directories into the unzipped source code directory:

whitneyknitter@Whitneys-Air ~ % cd ~/Downloads/icestudio-0.10

Since Mac OS is a little "too" user friendly and will block things from downloading and opening in the background during the build/installation of IceStudio, it's best to disable Gate Keeper for the next few steps:

whitneyknitter@Whitneys-Air icestudio-0.10 % sudo spctl --master-disable

Install IceStudio using the following command (npm_config_nwjs_process_arch=x64 npm install --force):

whitneyknitter@Whitneys-Air icestudio-0.10 % npm_config_nwjs_process_arch=x64 npm install --force

Once complete, launch the IceStudio IDE:

whitneyknitter@Whitneys-Air icestudio-0.10 % npm run start

First Launch Configuration

IceStudio will automatically launch into a new untitled project workspace. Start by selecting your target Lattice iCE FPGA board. My TinyFPGA boards are my personal favorite:

The first time you select a given FPGA board, you'll get a little warning warning that the target toolchain has not yet been installed. Click on the popup to install it.

Make sure you have an Internet connection and click OK.

IceStudio runs an underlying Python scrip to install the necessary packages and toolchain:

A pop-up will then appear asking to setup the drivers:

Once the pop-up appears that the drivers have been successfully enabled, everything is good to go for my TinyFPGAs. You can install any other toolchains and drivers at this point using the same method.

After installing the desired toolchain(s) and enabling the drivers, close IceStudio (will need to use ctrl+C in the Terminal window after closing the GUI window and the Terminal prints out "Waiting...") and re-enable Gate Keeper:

whitneyknitter@Whitneys-Air icestudio-0.10 % sudo spctl --master-enable

IceStudio is ready for regular use. However it does need to be launched from the source code directory using the npm package manager from the Terminal every time:

whitneyknitter@Whitneys-Air ~ % cd ~/Downloads/icestudio-0.10
whitneyknitter@Whitneys-Air icestudio-0.10 % npm run start

At the moment, even though the final packaged app installed from the.dmg installer does actually support the M1/M2 Macs, I found that no matter what I did the app somehow still thought my M2 Mac was x64 architecture so it kept trying to use the Intel Homebrew path (/usr/local/bin/) instead of the ARM-based Homebrew path (/opt/homebrew/bin/). And while I could verify and build projects, I could not upload them to my TinyFPGA. From reading through the Github issues for IceStudio I can tell this issue is being worked on.

Create New Project

After relaunching IceStudio with Gate Keeper re-enabled, it will open into a blank new project workspace. The tool menu for the parts library, plugin library, IceRok logic analyzer, serial terminal, and settings menu appears when hovering over the slide out menu on the left of the screen.

Open the parts library to drag + drop desired logic components into your design.

You can also write your own Verilog modules by writing your.v source file in a separate text editor then adding it to your IceStudio project by selecting File > Add as block... which will import the Verilog module as a block just like you would in a Vivado block design. Whatever signals you declare as inputs/outputs of the modules will be the pins that are available on the block in the IceStudio GUI.

I chose to wire up a simple AND gate with the output connected to pin 10 of my TinyFPGA B2:

Once completed, verify the design by clicking the </> icon on the lower righthand corner.

Keep in mind that conventional naming rules still apply to signals and ports (ie - can't start with a number or special character, can't contain illegal characters or spaces, etc.) I accidentally had a space in an output port name and I found that the error IceStudio kicks back for this is vague and doesn't make it clear that an illegal port name is the issue.

Build The Design

Once the design is verified and therefore free of syntax errors, it's time to build the design. Click the build (gear) icon in the lower righthand corner and wait for the Build done pop-up window:

Upload to Target Board

With the design verified and built, the final step is to upload it to the target board. Plug in the target FPGA board to the host computer running IceStudio and click the upload button (box with an arrow icon) in the lower righthand corner.

And there you have it! FPGA development on an M2 Mac! The importation of Verilog files as blocks is the aspect I see myself using heavily as it does allow me to create the more complex designs than the simple library of logic gate and flip flops will support. I fully expect this to be a go to in the future for me.

TinyFPGA B2 vs TinyFPGA BX

My TinyFPGA B2 worked perfectly, however my TinyFPGA BX would not connect to IceStudio at all to be able to upload bitstreams. Ultimately I found this to be an issue with how the the default serial driver in the latest versions of Mac OS doesn't attach properly to the TinyFPGA BX.

This requires a patch to the underlying TinyFPGA bootloader, tinyprog, which I have not figured out for Ventura yet. So I first need to figure out how to patch tinyprog in Ventura then figure out how to integrate that into the IceStudio installation. Which I'll post an update once I figure it out!