This one-page guide should get you quickly setup and running with the QORC SDK.
Contents
The hardware required is a development kit and a USB-UART cable.
QuickFeather Development Board + Micro-USB cable
Any 3.3V USB-UART cable, most common ones are FTDI FT232x or SiLabs CP210x based cables.
Clone the qorc-sdk repository :
git clone https://github.com/QuickLogic-Corp/qorc-sdk.git
NOTE: All the next steps below should be executed from the qorc-sdk directory.
cd qorc-sdk
The rest of the components can be automatically installed, and initialized using the helper script in the qorc-sdk envsetup.sh
This is the recommended method for new users.
source envsetup.sh
This will setup the following components within the qorc-sdk directory (on first run) and on subsequent run, initialize the tools to ready the development setup.
- ARM Cortex M4 Build Toolchain
- QuickLogic FPGA Build Toolchain
- QuickLogic TinyFPGA-Programmer-Application
- Minimal set of submodules in qorc-sdk repo
Alternatively, each of the components can be setup manually using the "Manual Setup" below.
Init and Update the (minimal) submodules in the qorc-sdk : s3-gateware, qorc-testapps, qorc-example-apps.
git submodule update --init qorc-example-apps git submodule update --init qorc-testapps git submodule update --init s3-gateware
Download archive according to the system configuration from: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads
Current stable version tested with qorc-sdk is
9-2020-q2-updateFor Linux systems, you can use:
wget -O gcc-arm-none-eabi-9-2020-q2-update-x86_64-linux.tar.bz2 -q --show-progress --progress=bar:force 2>&1 "https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2020q2/gcc-arm-none-eabi-9-2020-q2-update-x86_64-linux.tar.bz2?revision=05382cca-1721-44e1-ae19-1e7c3dc96118"
Extract the archive to
arm_toolchain_installdir inside qorc-sdkmkdir arm_toolchain_install tar xvjf gcc-arm-none-eabi-9-2020-q2-update-x86_64-linux.tar.bz2 -C ${PWD}/arm_toolchain_installAdd the toolchain to PATH (only for current terminal session)
export PATH=${PWD}/arm_toolchain_install/gcc-arm-none-eabi-9-2020-q2-update/bin:$PATHTest the toolchain installation:
which arm-none-eabi-gcc
should show something like:
"current directory path"/arm_toolchain_install/gcc-arm-none-eabi-9-2020-q2-update/bin/arm-none-eabi-gcc
If the path settings need to be permanent, it can be added to the
~/.bashrcor~/.bash_profile.Examples and illustrations are for example here: https://stackabuse.com/how-to-permanently-set-path-in-linux/
The recommended way to install the toolchain is using the latest prebuilt release here: quicklogic-fpga-toolchain releases
Download the installation script. For
v1.3.1, download : v1.3.1 installer scriptYou can use for download:
wget -O Symbiflow_v1.3.1.gz.run -q --show-progress --progress=bar:force 2>&1 https://github.com/QuickLogic-Corp/quicklogic-fpga-toolchain/releases/download/v1.3.1/Symbiflow_v1.3.1.gz.run
Set the directory path where the toolchain should be installed to
fpga_toolchain_install/v1.3.1dir inside the qorc-sdkexport INSTALL_DIR=${PWD}/fpga_toolchain_install/v1.3.1Run the installation script:
bash Symbiflow_v1.3.1.gz.run
This will setup the toolchain.
Initialize the toolchain environment :
export PATH="$INSTALL_DIR/quicklogic-arch-defs/bin:$INSTALL_DIR/quicklogic-arch-defs/bin/python:$PATH" source "$INSTALL_DIR/conda/etc/profile.d/conda.sh" conda activate
Test the toolchain installation:
ql_symbiflow -h
should display output similar to the below:
Below are the supported commands: To synthesize and dump a eblif file: >ql_symbiflow -synth -src <source_dir path> -d <device> -P <package> -t <top> -v <verilog file/files> -p <pcf file> To run synthesis, pack, place and route, generate bitstream: >ql_symbiflow -compile -src <source_dir path> -d <device> -P <package> -t <top> -v <verilog file/files> -p <pcf file> To dump the jlink/post_verilog/header/binary file: >ql_symbiflow -compile -src <source_dir path> -d <device> -P <package> -t <top> -v <verilog file/files> -p <pcf file> -dump <jlink/post_verilog/header/openocd/binary> Device supported:ql-eos-s3 Packages supported PD64,PU64,WR42 -h
Clone the TinyFPGA-Programmer repository recursively:
git clone --recursive https://github.com/QuickLogic-Corp/TinyFPGA-Programmer-Application.git
Install the
tinyfpgabdependency:pip3 install tinyfpgab
Install the
apiodrivers, and enable the serial driver:pip3 install apio apio drivers --serial-enable
Setup an alias to the programmer:
alias qfprog="python3 ${PWD}/TinyFPGA-Programmer-Application/tinyfpga-programmer-gui.py"This can be added to
.bashrcor.bash_profileto make it permanent as well.Test the programmer application:
qfprog --help
should show an output similar to below:
usage: tinyfpga-programmer-gui.py [-h] --mode [fpga-m4] [--m4app app.bin] [--appfpga appfpga.bin] [--bootloader boot.bin] [--bootfpga fpga.bin] [--reset] [--port /dev/ttySx] [--crc] [--checkrev] [--update] [--mfgpkg qf_mfgpkg/] optional arguments: -h, --help show this help message and exit --mode [fpga-m4] operation mode - m4/fpga/fpga-m4 --m4app app.bin m4 application program --appfpga appfpga.bin application FPGA binary --bootloader boot.bin, --bl boot.bin m4 bootloader program WARNING: do you really need to do this? It is not common, and getting it wrong can make you device non-functional --bootfpga fpga.bin FPGA image to be used during programming WARNING: do you really need to do this? It is not common, and getting it wrong can make you device non-functional --reset reset attached device --port /dev/ttySx use this port --crc print CRCs --checkrev check if CRC matches (flash is up-to-date) --update program flash only if CRC mismatch (not up-to-date) --mfgpkg qf_mfgpkg/ directory containing all necessary binaries
Use your favorite serial terminal application, common ones include:
For accessing serial ports on Linux, the user must be added into the dialout group.
To check if user is already part of dialout:
id -Gn $USER | grep -c "dialout"
will output 1 if already in group or 0 if not.
To add current user to dialout group:
sudo usermod -a -G dialout $USER
You may need to logout and back in for the new group to take effect.
Plug in the QuickFeather board and set it to flash mode, with the sequence:
- press
RSTbutton, blue LED should start flashing - within 5 seconds, press the
USRbutton, green LED should now start flashing/breathing. - This indicates that the QuickFeather board is in
flash mode
Check the output of lsusb like below to see if the QuickFeather USB-CDC is detected correctly:
lsusb | grep OpenMoko
should display one of the IDs 1d50:6140 or 1d50:6130, like below:
Bus 002 Device 029: ID 1d50:6140 OpenMoko, Inc. or Bus 002 Device 029: ID 1d50:6130 OpenMoko, Inc.
As this is a developing ecosystem, expect some churn at this time, with changes in the toolchains, flash programmer and bootloader.
To ensure that you are using the bleeding edge of the setup (recommended, unless you are specifically looking for a particular version), it is recommended to update the bootloader.
Bootloader has updates in the following qorc-sdk versions:
- v1.5.0 [https://github.com/QuickLogic-Corp/qorc-sdk/releases/tag/v1.5.0] [08 DEC 2020]
To update the Bootloader on the Development Kit, follow the Build, Flash, Run as below.
Navigate to qf_bootloader application build folder and run make
cd qf_apps/qf_bootloader/GCC_Project make
Set the QuickFeather in flash mode, with the sequence:
- press
RSTbutton, blue LED should start flashing - within 5 seconds, press the
USRbutton, green LED should now start flashing/breathing. - This indicates that the QuickFeather board is in
flash mode
Flash the qf_bootloader app into QuickFeather with:
qfprog --port <PORTNAME> --bootloader output/bin/qf_bootloader.bin --mode m4
where the <PORTNAME>: is the UART port exposed by the QuickFeather.
This would be of the form:
COM##on PC/Windows/dev/ttyS##on PC/wsl1/wsl2/Ubuntu18+ (where the ## is the same as the COM## shown by device manager under Windows)/dev/ttyACM#on PC/Ubuntu18+
Once flashing is completed, press the RST button to reset the QuickFeather, the new bootloader should be executed.
The qf_apps/qf_helloworldsw application in the qorc-sdk is the (almost) traditional hello world application.
USB2SERIAL peripheral.USB2SERIAL peripheral is a USB-CDC (UART) peripheral programmed into the FPGA of the EOSS3 by the M4 code.Navigate to qf_helloworldsw build folder and run make
cd qf_apps/qf_helloworldsw/GCC_Project make
Set the QuickFeather in flash mode, with the sequence:
- press
RSTbutton, blue LED should start flashing - within 5 seconds, press the
USRbutton, green LED should now start flashing/breathing. - This indicates that the QuickFeather board is in
flash mode
Flash the qf_helloworldsw app into QuickFeather with:
qfprog --port <PORTNAME> --m4app output/bin/qf_helloworldsw.bin --mode m4
where the <PORTNAME>: is the UART port exposed by the QuickFeather.
This would be of the form:
COM##on PC/Windows/dev/ttyS##on PC/wsl1/wsl2/Ubuntu18+ (where the ## is the same as the COM## shown by device manager under Windows)/dev/ttyACM#on PC/Ubuntu18+
Once flashing is completed, press the RST button to reset the QuickFeather.
Do not press USR button this time, and then the bootloader would load the newly flashed application above.
Use your favorite Serial Port Application to connect to the QuickFeather USB-CDC port.
You should see an output like below:
########################## Quicklogic QuickFeather LED / User Button Test SW Version: qorc-sdk/qf_apps/qf_helloworldsw Sep 20 2020 14:24:43 ########################## #******************* Command Line Interface App SW Version: qorc-sdk/qf_apps/qf_helloworldsw #******************* [0] >
diag submenu option is available, and can be used to toggle the RGB leds or detect the USR button press:[0] > prompt, which is the level 0 prompt, use:diag redto toggle the red leddiag greento toggle the green leddiag blueto toggle the blue led
[0] > prompt, which is the level 0 prompt, do:- Keep the USR button pressed (connected to IO_6 on QuickFeather)Execute:
diag userbuttonto check stateYou should seePressed - Without the USR button pressedExecute:
diag userbuttonto check stateYou should seeNot pressed
The qf_apps/qf_helloworldhw application in the qorc-sdk is a traditional fpga hello world application - a "blinky"
The M4 code loads a basic FPGA design which blinks the green LED on the quickfeather.
qf_apps/qf_helloworldhw/fpga/rtl directorymake, the FPGA design is compiled into a bitstream, in a header format.Navigate to qf_helloworldhw build folder and run make
cd qf_apps/qf_helloworldhw/GCC_Project make
Set the QuickFeather in flash mode, with the sequence:
- press
RSTbutton, blue LED should start flashing - within 5 seconds, press the
USRbutton, green LED should now start flashing/breathing. - This indicates that the QuickFeather board is in
flash mode
Flash the qf_helloworldhw app into QuickFeather with:
qfprog --port <PORTNAME> --m4app output/bin/qf_helloworldhw.bin --mode m4
where the <PORTNAME>: is the UART port exposed by the QuickFeather.
This would be of the form:
COM##on PC/Windows/dev/ttyS##on PC/wsl1/wsl2/Ubuntu18+ (where the ## is the same as the COM## shown by device manager under Windows)/dev/ttyACM#on PC/Ubuntu18+
Once flashing is completed, press the RST button to reset the QuickFeather.
Do not press USR button this time, and then the bootloader would load the newly flashed application above.
Once the application is loaded, you can see the blinky in action - the green LED of the QuickFeather starts blinking.
[Optional]
If you want to look at the debug output, connect a USB-UART cable between the QuickFeather UART and the PC as described above.
Use your favorite Serial Port Application to connect to the port exposed by the USB-UART cable.
You should see an output like below, and nothing else will follow:
########################## Quicklogic QuickFeather Standalone FPGA SW Version: qorc-sdk/qf_apps/qf_helloworldhw Sep 20 2020 14:24:43 ##########################
Anytime a new terminal is opened, the already installed tools need to be initialized before any of the apps can be used.
If you had used the automated setup using the helper script, then the same script can be run again to initialize all components.
cd "path to qorc-sdk" source envsetup.sh
If you have setup the components manually, then corresponding to the install instructions above, the initialization seqeunce can be followed.
The sequence that can be followed is:
cd "path to qorc-sdk"
export PATH=${PWD}/arm_toolchain_install/gcc-arm-none-eabi-9-2020-q2-update/bin:$PATH
export INSTALL_DIR=${PWD}/fpga_toolchain_install/v1.3.1
export PATH="$INSTALL_DIR/quicklogic-arch-defs/bin:$INSTALL_DIR/quicklogic-arch-defs/bin/python:$PATH"
source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
conda activate
alias qfprog="python3 ${PWD}/TinyFPGA-Programmer-Application/tinyfpga-programmer-gui.py"
Once the sequence is executed, the environment is ready to be used for build/flash/run of any qorc-sdk application.
You can open a new terminal, execute the initialization sequence as above, and try the "Hello World" applications
That's it!
If you have got this far, then the setup is verified, and you can now build and flash any application in the qorc-sdk to the QuickFeather.
The next step would be checkout the goingfurther.rst for exploring a few more advanced applications, which can give a feel of the various ways to use the qorc-sdk to build applications (coming soon).
You can look at the applications in qf_apps, qorc-testapps, qorc-example-apps and qf_vr_apps for more examples of what can be done with the qorc-sdk.