How to...¶
Install the toolchain¶
- Install Python 2.7
- Launch the toolchain installation process
Go to Tools > Toolchain > Install. Be patient for the toolchain installation.
Note
When the toolchain is installed, the menu option changes to Tools > Toolchain > Update. Also, the toolchain can be restored to default in Tools > Toolchain > Reset default.
Update the toolchain¶
- Connect to the Internet
- Launch the toolchain updating process
Go to Tools > Toolchain > Update. Be patient for the toolchain update.
Install the drivers¶
- Install the toolchain (required for Windows)
- Enable the FTDI drivers
Go to Tools > Drivers > Enable. Each OS has a different process. This configuration requires administration privileges.
Note
In Windows, an external application (Zadig) is launched to replace the existing FTDI driver of the Interface 0 by libusbK.
In MacOS this operation requires Internet connection to allow Homebrew to install libffi and libftdi packages.
Hint
To revert the drivers configuration go to Tools > Drivers > Disable
Create a project¶
Create a new project
Go to Edit > New. A new window will be opened.
- Add blocks
There are different types of blocks:
Input/Output blocks
Click on Basic > Input or Basic > Output, write the block’s name and press OK or Enter.
These blocks can be configured as virtual (green). Then, the FPGA pin selector won’t be shown.
Also, it can be configured as buses using the
[x:y]
notation (x
is the most significant bit).
Constant blocks
Click on Basic > Constant, write the block’s name and press OK or Enter.
These blocks can be configures as local. Then, this parameter won’t be exported.
Code blocks
Click on Basic > Code, add the code ports. Port names are separated by a comma. E.g.:
a, b
.This block contains a text editor to write your module in verilog code. Module header and footer are not required.
Info blocks
Click on Basic > Info.
This block contains a text editor to add comments about the project.
It can be converted into a Readonly text block by editing the block (double-click).
Bit blocks
Click on Bit > 0 or Bit > 1.
These blocks are low and high logic drivers.
Logic blocks
Go to the Logic menu and select a block. This menu contains Gates, Combinational blocks and Sequential blocks.
Setup blocks
Click on Setup > Pull up or Setup > Tri-state.
The Pull up block must be connected to input ports in order to configure a pull up in the FPGA.
In this example we are going to implement an AND logic gate with its input/output pins connected to the FPGA I/O.
- Connect the blocks
Select your board
Go to Select > Board and select IceZUM Alhambra, Kéfir I iCE40-HX4K, Nandland Go board, iCE40-HX8K Breakout Board, iCEstick Evaluation Kit or icoBOARD 1.0.
Set FPGA I/O pins
Select all Input/Output blocks’ pins.
Save the project
Go to Edit > Save as and select the project name, for example myProject.
It will be saved as an .ice file.
Upload a bitstream¶
Open a project
Go to Edit > Open... and select an .ice file.
Verify the project
Go to Tools > Verify.
This option checks the generated verilog code using
apio verify
.Build the project
Go to Tools > Build.
This option generates a bitstream using
apio build
.Upload the project
Connect your FPGA board and press Tools > Upload. This option uses
apio upload
.
Create a block¶
Open a project
Go to Edit > Open project and select an .ice file. It is recommended to set all the I/O ports non-FPGA ports (green) to create a block.
Verify the project
Go to Tools > Verify.
Add the project information
Go to Edit > Preferences > Project information.
Save the project
Go to Edit > Save.
Add a project as block¶
- Open or create a new project
Import the custom block
Go to Edit > Add as block... and select an .ice file.
Examine the custom block
Complex blocks can be examined by double clicking the block.
Add a collection¶
Go to Tools > Collections > Add and select a collection package (ZIP file).
Select a collection¶
Go to Select > Collections. Select a collection. The first item is the “Default” collection that is the one stored in the application.
View the selected collection info¶
Go to View > Collection info. A new window will appear with the README.md file content.
Create a collection package¶
- Create one or more collections
You can use the icm cli tool to create and update a collection.
Collection/ ├── blocks │ ├── category1 │ │ ├── block1.ice │ │ └── subcategory1 │ │ ├── block11.ice │ │ └── block12.ice │ └── category2 │ └── block2.ice ├── examples │ ├── example1.ice │ ├── example2.ice │ └── example3.ice ├── locale │ ├── en │ │ └── en.po │ ├── es_ES │ │ └── es_ES.po │ └── translation.js ├── LICENSE ├── package.json └── README.md
- ZIP all your collections
Create a ZIP file with all your created collections at the main level.
Collections.zip | ├── Collections 1 │ └── ... └── Collections 2 └── ...
Note
The file package.json must exists, and also the blocks directory and/or the examples directory. The locale directory is optional. More information in the Default collection.
Include a list file¶
If your code block contains a list file(s), for example:
$readmemh("rom.list", rom);
- Save the ice project
- Copy the list file(s) in the project directory
- Build and upload the project
Also you can include explicitly a list file in the header of a code block:
// @include rom.list
Include a verilog (header) file¶
If your code block includes a verilog (header) file(s), for example:
// @include lib.vh
// @include math.v
`include "lib.vh"
- Save the ice project
- Copy the verilog (header) file(s) in the project’s directory
- Build and upload the project
Configure a remote host¶
I you want to use a RPi, eg pi@192.168.0.22, or another computer from Icestudio as a client, first configure the host:
- Copy your SSH public key into the server
$ ssh-keygen $ ssh-copy-id -i .ssh/id_rsa.pub pi@192.168.0.22
- Install apio in the server
$ ssh pi@192.168.0.22 $ sudo pip install -U apio $ apio install --all $ apio drivers --enable # For FTDI devices
Enter the host name in Icestudio, Edit > Remote hostname
Now, Verify, Build and Upload tools will run in the selected host
Close the application¶
Go to File > Quit or click the application’s close button. If there are unsaved changes an alert will appear to confirm or cancel the action: