Add an example and documentation for QuickLogic K4N8 target

.github/scripts/build-examples.sh

@@ -91,6 +91,14 @@ case "$fpga_family" in
     esac
   done
   ;;
+  qlf_k4n8) for example in $examples; do
+    case $example in
+      "counter") tuttest_exec ${snippets} qlf_k4n8/btn_counter/README.rst:qlf_k4n8-counter ;;
+      *) echo "ERROR: Unknown example name: $example" >&2
+        exit 1 ;;
+    esac
+  done
+  ;;
   *) echo "ERROR: Unknown fpga_family: $fpga_family" >&2
     exit 1
   ;;

.github/scripts/generate_job_matrices.py

@@ -105,6 +105,16 @@ def get_jobs(
         'surelog': "-parse -DSYNTHESIS" if usesSurelog else ""
     } for osver in osvers])
 
+    jobs.extend([{
+        'name': "Surelog" if usesSurelog else "Default",
+        'runs-on': runs_on,
+        'fpga-fam': "qlf_k4n8",
+        'os': osver[0],
+        'os-version': osver[1],
+        'example': "counter",
+        'surelog': "-parse -DSYNTHESIS" if usesSurelog else ""
+    } for osver in osvers])
+
     return jobs
 
 for distribution in ['debian', 'ubuntu', 'fedora', 'centos']:

README.md

@@ -17,7 +17,7 @@
 </p>
 
 This repository provides example FPGA designs that can be built using the F4PGA open source toolchain.
-These examples target the Xilinx 7-Series and the QuickLogic EOS S3 devices.
+These examples target the Xilinx 7-Series, the QuickLogic EOS S3 and K4N8 devices.
 
 * Please refer to the [![](https://img.shields.io/website?longCache=true&style=flat-square&label=Documentation%20For%20Users&up_color=231f20&up_message=%E2%9E%9A&url=https%3A%2F%2Ff4pga-examples.readthedocs.io%2Fen%2Flatest%2Findex.html&labelColor=fff)](https://f4pga-examples.readthedocs.io)
   for a proper guide on how to run these examples, as well as instructions on how to build and compile your own HDL designs using
@@ -27,7 +27,7 @@ These examples target the Xilinx 7-Series and the QuickLogic EOS S3 devices.
 
 The repository includes:
 
-* [xc7/](./xc7) and [eos-s3/](./eos-s3) - Examples for Xilinx 7-Series and EOS-S3 devices, including:
+* [xc7/](./xc7), [eos-s3/](./eos-s3) and [qlf_k4n8/](./qlf_k4n8)- Examples for Xilinx 7-Series, EOS-S3 and K4N8 devices, including:
 
   * Verilog code
 

docs/building-examples.rst

@@ -29,6 +29,13 @@ Select your FPGA family:
 
          export FPGA_FAM="eos-s3"
 
+   .. group-tab:: K4N8
+
+      .. code-block:: bash
+         :name: fpga-fam-qlf_k4n8
+
+         export FPGA_FAM="qlf_k4n8"
+
 Next, prepare the environment:
 
 .. code-block:: bash
@@ -98,3 +105,20 @@ Then, follow the guidelines for each example:
 .. toctree::
 
    eos-s3/btn_counter
+
+
+QuickLogic K4N8
+===============
+
+Enter the directory that contains examples for QuickLogic K4N8:
+
+.. code-block:: bash
+   :name: enter-dir-qlf_k4n8
+
+   cd qlf_k4n8
+
+Then, follow the guidelines for each example:
+
+.. toctree::
+
+   qlf_k4n8/btn_counter

docs/collect_readmes.py

@@ -10,7 +10,7 @@
     'zybo': 'Zybo Z7',
     'nexys_video': 'Nexys Video',
 }
-families = ('xc7', 'eos-s3')
+families = ('xc7', 'eos-s3', 'qlf_k4n8')
 inlines = ('literal', 'strong', 'reference')
 
 

docs/development/running-ci-locally.rst

@@ -9,7 +9,7 @@ For this, you will need `tuttest <https://github.com/antmicro/tuttest/>`_, which
 
     pip install git+https://github.com/antmicro/tuttest
 
-* ``<fpga-family>`` is one of ``{eos-s3, xc7}`` (the two currently covered platforms - EOS-S3 and Xilinx series 7).
+* ``<fpga-family>`` is one of ``{eos-s3, xc7, qlf_k4n8}`` (the three currently covered platforms - EOS-S3, K4N8 and Xilinx series 7).
 
 * ``<os>`` is one of ``{ubuntu, debian, centos}`` (currently supported operating systems).
 

docs/getting.rst

@@ -107,6 +107,13 @@ Select your target FPGA family:
 
          export FPGA_FAM=eos-s3
 
+   .. group-tab:: K4N8
+
+      .. code-block:: bash
+         :name: fpga-fam-qlf_k4n8
+
+         export FPGA_FAM=qlf_k4n8
+
 Next, setup Conda and your system's environment, and download architecture definitions:
 
 .. NOTE::
@@ -137,6 +144,13 @@ Next, setup Conda and your system's environment, and download architecture defin
 
          export F4PGA_PACKAGES='install-ql ql-eos-s3_wlcsp'
 
+   .. group-tab:: K4N8
+
+      .. code-block:: bash
+         :name: packages-qlf_k4n8
+
+         export F4PGA_PACKAGES='install-ql qlf_k4n8-qlf_k4n8_umc22_fast_qlf_k4n8-qlf_k4n8_umc22_fast qlf_k4n8-qlf_k4n8_umc22_qlf_k4n8-qlf_k4n8_umc22 qlf_k4n8-qlf_k4n8_umc22_slow_qlf_k4n8-qlf_k4n8_umc22_slow'
+
 .. code-block:: bash
    :name: get-packages
 
@@ -157,6 +171,7 @@ If the above commands exited without errors, you have successfully installed and
 
   * Subdir :ghsrc:`xc7` for the Artix-7 devices
   * Subdir :ghsrc:`eos-s3` for the EOS S3 devices
+  * Subdir :ghsrc:`qlf_k4n8` for the K4N8 devices
 
 .. HINT::
   Sometimes it may be preferable to get the latest versions of the tools before the pinned versions in this repository

docs/index.rst

@@ -7,6 +7,7 @@ It currently focuses on the following FPGA families:
 
 - Artix-7 from Xilinx,
 - EOS-S3 from QuickLogic.
+- K4N8 from QuickLogic.
 
 Follow this guide to:
 
@@ -24,7 +25,7 @@ F4PGA is a fully open source toolchain for the development of FPGAs, currently t
 
 - Xilinx's 7-Series.
 - Lattice's ICE40 and ECP5.
-- QuickLogic's EOS-S3.
+- QuickLogic's EOS-S3 and K4N8.
 
 Gain valuable information about the flows and the tools in section :ref:`Design Flows <f4pga:Flows>` at
 :doc:`F4PGA Documentation <f4pga:index>`.

docs/qlf_k4n8/btn_counter.rst

@@ -0,0 +1,2 @@
+.. jinja:: qlf_k4n8_btn_counter
+   :file: templates/example.jinja

qlf_k4n8/btn_counter/Makefile

@@ -0,0 +1,21 @@
+ifdef F4PGA_USE_DEPRECATED
+all:
+# -d: Device
+# -P: Part name
+# -v: Verilog source
+# -t: Top
+# -p: PCF Constrains
+	ql_symbiflow -compile \
+	  -d ql-eos-s3 \
+	  -P PD64 \
+	  -v btn_counter.v \
+	  -t top \
+	  -p chandalar.pcf \
+	  -dump jlink \
+	  -dump openocd \
+	  -dump header \
+	  -dump binary
+else
+all:
+	f4pga -vvv build --flow ./flow.json
+endif

qlf_k4n8/btn_counter/README.rst

@@ -0,0 +1,10 @@
+Button counter
+~~~~~~~~~~~~~~
+
+This example design features a simple 4-bit counter driving LEDs. To build the
+counter example, run the following command:
+
+.. code-block:: bash
+   :name: qlf_k4n8-counter
+
+   make -C btn_counter

qlf_k4n8/btn_counter/btn_counter.v

@@ -0,0 +1,13 @@
+module top (
+    input  wire       clk,
+    output wire [3:0] led
+);
+
+  reg [3:0] cnt;
+  initial cnt <= 0;
+
+  always @(posedge clk) cnt <= cnt + 1;
+
+  assign led = cnt;
+
+endmodule

qlf_k4n8/btn_counter/chandalar.pcf

@@ -0,0 +1,5 @@
+set_clk clk      clk
+set_io  led[0]   A2F_GPIO6_4
+set_io  led[1]   A2F_GPIO6_5
+set_io  led[2]   A2F_GPIO6_6
+set_io  led[3]   A2F_GPIO6_7

qlf_k4n8/btn_counter/dummy.sdc

@@ -0,0 +1 @@
+create_clock -period 10.0 clk -waveform {0.000 5.000}

qlf_k4n8/btn_counter/flow.json

@@ -0,0 +1,26 @@
+{
+    "default_part": "K4N8",
+    "values": {
+        "top": "top"
+    },
+    "dependencies": {
+        "sources": [
+            "./btn_counter.v"
+        ],
+        "synth_log": "synth.log",
+        "pack_log": "pack.log",
+        "analysis_log": "analysis.log"
+    },
+    "K4N8": {
+        "default_target": "bitstream",
+        "dependencies": {
+            "build_dir": "build",
+            "pcf": "./chandalar.pcf",
+            "sdc": "./dummy.sdc"
+        },
+        "values": {
+            "part": "ql-k4n8_slow",
+            "package": "PD64"
+        }
+    }
+}

qlf_k4n8/environment.yml

@@ -0,0 +1,34 @@
+# Copyright (C) 2020-2022 F4PGA Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+name: qlf_k4n8
+
+channels:
+  - litex-hub
+
+dependencies:
+  - litex-hub::yosys=0.19_10_g0098b32c6=20220706_001518_py37
+  - litex-hub::symbiflow-yosys-plugins=1.0.0_7_1002_gd149693=20220706_001518
+  - litex-hub::vtr-optimized=8.0.0_5664_gb7a94b90a=20220706_001518
+  - make
+  - lxml
+  - simplejson
+  - intervaltree
+  - git
+  - pip
+  # Packages installed from PyPI
+  - pip:
+    - -r requirements.txt

qlf_k4n8/requirements.txt

@@ -0,0 +1,20 @@
+# Copyright (C) 2020-2022 F4PGA Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+-r ../common/requirements.txt
+
+serial
+git+https://github.com/QuickLogic-Corp/ql_fasm@master#egg=qlf_fasm