Merge pull request #163 from umarcor/doc-fpgas

doc: declare FPGA compatibility list through YAML file

.gitignore

@@ -43,3 +43,4 @@ build/
 /doc/_build/
 /doc/_theme/
 /doc/compatibility/boards.inc
+/doc/compatibility/fpga.inc

doc/FPGAs.yml

@@ -0,0 +1,234 @@
+Anlogic:
+
+  - Description: EG4
+    Model: S20
+    URL: http://www.anlogic.com/prod_view.aspx?TypeId=10&Id=168&FId=t3:10:3
+    Memory: OK
+    Flash: AS
+
+  - Description: SALELF 2
+    Model: EF2M45
+    URL: http://www.anlogic.com/prod_view.aspx?TypeId=12&Id=170&FId=t3:12:3
+    Memory: OK
+    Flash: OK
+
+
+Cologne Chip:
+
+  - Description: GateMate Series
+    Model:
+      - CCGM1A1
+      - CCGM1A2
+      - CCGM1A4
+      - CCGM1A9
+      - CCGM1A16
+      - CCGM1A25
+    URL: https://colognechip.com/programmable-logic/gatemate/
+    Memory: OK
+    Flash: OK
+
+
+Efinix:
+
+  - Description: Trion
+    Model: T8
+    URL: https://www.efinixinc.com/products-trion.html
+    Memory: NA
+    Flash: OK
+
+  - Description: Titanium
+    Model: Ti60
+    URL: https://www.efinixinc.com/products-titanium.html
+    Memory: NA
+    Flash: OK
+
+
+Gowin:
+
+  - Description: GW1N
+    Model:
+     - GW1N-1
+     - GW1N-4
+     - GW1NR-9
+     - GW1NS-2C
+     - GW1NSR-4C
+    URL: https://www.gowinsemi.com/en/product/detail/2/
+    Memory: OK
+    Flash: IF
+
+
+Intel:
+
+  - Description: Cyclone III
+    Model: EP3C16
+    URL: https://www.intel.com/content/www/us/en/programmable/products/fpga/cyclone-series/cyclone-iii/support.html
+    Memory: OK
+    Flash: OK
+
+  - Description: Cyclone IV CE
+    Model: EP4CE22
+    URL: https://www.intel.com/content/www/us/en/products/programmable/fpga/cyclone-iv/features.html
+    Memory: OK
+    Flash: OK
+
+  - Description: Cyclone V E
+    Model:
+      - 5CEA2
+      - 5CEBA4
+    URL: https://www.intel.com/content/www/us/en/products/programmable/fpga/cyclone-v.html
+    Memory: OK
+    Flash: OK
+
+  - Description: Cyclone 10 LP
+    Model: 10CL025
+    URL: https://www.intel.com/content/www/us/en/products/programmable/fpga/cyclone-10.html
+    Memory: OK
+    Flash: OK
+
+
+Lattice:
+
+  - Description: CrossLink-NX
+    Model: LIFCL-40
+    URL: https://www.latticesemi.com/en/Products/FPGAandCPLD/CrossLink-NX
+    Memory: OK
+    Flash: OK
+
+  - Description: ECP5
+    Model:
+      - 25F
+      - 5G 85F
+    URL: http://www.latticesemi.com/Products/FPGAandCPLD/ECP5
+    Memory: OK
+    Flash: OK
+
+  - Description: iCE40
+    Model:
+      - HX1K
+      - HX4K
+      - HX8K
+      - UP5K
+    URL: https://www.latticesemi.com/en/Products/FPGAandCPLD/iCE40
+    Memory: NA
+    Flash: AS
+
+  - Description: MachXO2
+    Model:
+      - '256'
+      - '640'
+      - '640U'
+      - '1200'
+      - '1200U'
+      - '2000'
+      - '2000U'
+      - '4000'
+      - '7000'
+    URL: https://www.latticesemi.com/en/Products/FPGAandCPLD/MachXO2
+    Memory: OK
+    Flash: OK
+
+  - Description: MachXO3D
+    Model:
+      - '4300'
+      - '9400'
+    URL: http://www.latticesemi.com/en/Products/FPGAandCPLD/MachXO3D.aspx
+    Memory: OK
+    Flash: OK
+
+  - Description: MachXO3LF
+    Model:
+      - '640'
+      - '1300'
+      - '2100'
+      - '4300'
+      - '6900'
+      - '9400'
+    URL: http://www.latticesemi.com/en/Products/FPGAandCPLD/MachXO3.aspx
+    Memory: OK
+    Flash: OK
+
+
+Xilinx:
+
+  - Description: Artix 7
+    Model:
+      - xc7a35ti
+      - xc7a50t
+      - xc7a75t
+      - xc7a100t
+      - xc7a200t
+    URL: https://www.xilinx.com/products/silicon-devices/fpga/artix-7.html
+    Memory: OK
+    Flash: OK
+
+  - Description: Kintex 7
+    Model:
+      - xc7k160t
+      - xc7k325t
+    URL: https://www.xilinx.com/products/silicon-devices/fpga/kintex-7.html#productTable
+    Memory: OK
+    Flash: NT
+
+  - Description: Spartan 3
+    Model: xc3s200
+    URL: https://www.xilinx.com/products/silicon-devices/fpga/spartan-3.html
+    Memory: OK
+    Flash: NA
+
+  - Description: Spartan 6
+    Model:
+      - xc6slx9
+      - xc6slx16
+      - xc6slx25
+      - xc6slx45
+    URL: https://www.xilinx.com/products/silicon-devices/fpga/spartan-6.html
+    Memory: OK
+    Flash: OK
+
+  - Description: Spartan 7
+    Model:
+      - xc7s15
+      - xc7s25
+      - xc7s50
+    URL: https://www.xilinx.com/products/silicon-devices/fpga/spartan-7.html
+    Memory: OK
+    Flash: OK
+
+  - Description: XC9500XL
+    Model:
+      - xc9536xl
+      - xc9572xl
+      - xc95144xl
+      - xc95188xl
+    URL: https://www.xilinx.com/support/documentation/data_sheets/ds054.pdf
+    Memory: NA
+    Flash: OK
+
+  - Description: XC2C (coolrunner II)
+    Model: xc2c32a
+    URL: https://www.xilinx.com/support/documentation/data_sheets/ds090.pdf
+    Memory: TBD
+    Flash: OK
+
+  - Description: XCF
+    Model:
+      - xcf01s
+      - xcf02s
+      - xcf04s
+    URL: https://www.xilinx.com/products/silicon-devices/configuration-memory/platform-flash.html
+    Memory: NA
+    Flash: OK
+
+  - Description: Zynq7000
+    Model:
+      - xc7z010
+      - xc7z020
+    URL: https://www.xilinx.com/products/silicon-devices/soc/zynq-7000.html
+    Memory: OK
+    Flash: NA
+
+  - Description: ZynqMPSoC
+    Model: xczu2cg
+    URL: https://www.xilinx.com/products/silicon-devices/soc/zynq-ultrascale-mpsoc.html
+    Memory: OK
+    Flash: NA

doc/compatibility/fpga.rst

@@ -3,36 +3,7 @@
 FPGAs
 #####
 
-============= =================================================================================================================================== ====== =====
+.. include:: fpga.inc
- Vendor       Model                                                                                                                               Memory Flash
-============= =================================================================================================================================== ====== =====
-     Anlogic  `EG4S20 <http://www.anlogic.com/prod_view.aspx?TypeId=10&Id=168&FId=t3:10:3>`__                                                     OK     AS
-     Anlogic  `EF2M45 <http://www.anlogic.com/prod_view.aspx?TypeId=12&Id=170&FId=t3:12:3>`__                                                     OK     OK
-Cologne Chip  `GateMate Series <https://colognechip.com/programmable-logic/gatemate/>`__                                                          OK     OK
-      Efinix  `Trion T8 <https://www.efinixinc.com/products-trion.html>`__                                                                        NA     OK
-      Efinix  `Titanium Ti60 <https://www.efinixinc.com/products-titanium.html>`__                                                                NA     OK
-       Gowin  `GW1N (GW1N-1, GW1N-4, GW1NR-9, GW1NS-2C, GW1NSR-4C) <https://www.gowinsemi.com/en/product/detail/2/>`__                            OK     IF
-       Intel  Cyclone III `EP3C16 <https://www.intel.com/content/www/us/en/programmable/products/fpga/cyclone-series/cyclone-iii/support.html>`__ OK     OK
-       Intel  Cyclone IV CE `EP4CE22 <https://www.intel.com/content/www/us/en/products/programmable/fpga/cyclone-iv/features.html>`__             OK     OK
-       Intel  Cyclone V E `5CEA2, 5CEBA4 <https://www.intel.com/content/www/us/en/products/programmable/fpga/cyclone-v.html>`__                   OK     OK
-       Intel  Cyclone 10 LP `10CL025 <https://www.intel.com/content/www/us/en/products/programmable/fpga/cyclone-10.html>`__                      OK     OK
-     Lattice  `CrossLink-NX (LIFCL-40) <https://www.latticesemi.com/en/Products/FPGAandCPLD/CrossLink-NX>`__                                      OK     OK
-     Lattice  `ECP5 (25F, 5G 85F) <http://www.latticesemi.com/Products/FPGAandCPLD/ECP5>`__                                                       OK     OK
-     Lattice  `iCE40 (HX1K, HX4K, HX8K, UP5K) <https://www.latticesemi.com/en/Products/FPGAandCPLD/iCE40>`__                                      NA     AS
-     Lattice  `MachXO2 <https://www.latticesemi.com/en/Products/FPGAandCPLD/MachXO2>`__                                                           OK     OK
-     Lattice  `MachXO3D <http://www.latticesemi.com/en/Products/FPGAandCPLD/MachXO3D.aspx>`__                                                     OK     OK
-     Lattice  `MachXO3LF <http://www.latticesemi.com/en/Products/FPGAandCPLD/MachXO3.aspx>`__                                                     OK     OK
-      Xilinx  Artix 7 `xc7a35ti, xc7a50t, xc7a75t, xc7a100t, xc7a200t <https://www.xilinx.com/products/silicon-devices/fpga/artix-7.html>`__      OK     OK
-      Xilinx  Kintex 7 `xc7k160t, xc7k325t <https://www.xilinx.com/products/silicon-devices/fpga/kintex-7.html#productTable>`__                   OK     NT
-      Xilinx  Spartan 3 `xc3s200 <https://www.xilinx.com/products/silicon-devices/fpga/spartan-3.html>`__                                         OK     NA
-      Xilinx  Spartan 6 `xc6slx9, xc6slx16, xc6slx25, xc6slx45 <https://www.xilinx.com/products/silicon-devices/fpga/spartan-6.html>`__           OK     OK
-      Xilinx  Spartan 7 `xc7s15, xc7s25, xc7s50 <https://www.xilinx.com/products/silicon-devices/fpga/spartan-7.html>`__                          OK     OK
-      Xilinx  XC9500XL `xc9536xl, xc9572xl, xc95144xl, xc95188xl <https://www.xilinx.com/support/documentation/data_sheets/ds054.pdf>`__          NA     OK
-      Xilinx  XC2C (coolrunner II) `xc2c32a <https://www.xilinx.com/support/documentation/data_sheets/ds090.pdf>`__                               TBD    OK
-      Xilinx  XCF `xcf01s, xcf02s, xcf04s <https://www.xilinx.com/products/silicon-devices/configuration-memory/platform-flash.html>`__           NA     OK
-      Xilinx  Zynq7000 `xc7z010, xc7z020 <https://www.xilinx.com/products/silicon-devices/soc/zynq-7000.html>`__                                  OK     NA
-      Xilinx  ZynqMPSoC `xczu2cg <https://www.xilinx.com/products/silicon-devices/soc/zynq-ultrascale-mpsoc.html>`__                              OK     NA
-============= =================================================================================================================================== ====== =====
 
 * IF: Internal Flash
 * AS: Active Serial flash mode

doc/conf.py

@@ -11,8 +11,12 @@ ROOT = Path(__file__).resolve().parent
 sys_path.insert(0, abspath("."))
 
 
-from boards import ReadDataFromYAML, DataToTable
+from data import (
-
+    ReadBoardDataFromYAML,
+    BoardDataToTable,
+    ReadFPGADataFromYAML,
+    FPGADataToTable
+)
 
 # -- General configuration ------------------------------------------------
 
@@ -111,4 +115,9 @@ extlinks = {
 # -- Generate partial board compatibility page (`board.inc`) with data from `boards.yml`
 
 with (ROOT / "compatibility/boards.inc").open("w", encoding="utf-8") as wptr:
-    wptr.write(DataToTable(ReadDataFromYAML()))
+    wptr.write(BoardDataToTable(ReadBoardDataFromYAML()))
+
+# -- Generate partial FPGA compatibility page (`fpga.inc`) with data from `FPGAs.yml`
+
+with (ROOT / "compatibility/fpga.inc").open("w", encoding="utf-8") as wptr:
+    wptr.write(FPGADataToTable(ReadFPGADataFromYAML()))

doc/data.py

@@ -1,3 +1,4 @@
+from typing import List, Union
 from pathlib import Path
 from dataclasses import dataclass
 from yaml import load as yaml_load, Loader as yaml_loader, dump as yaml_dump
@@ -18,13 +19,13 @@ class Board:
     Constraints: str = None
 
 
-def ReadDataFromYAML():
+def ReadBoardDataFromYAML():
     with (ROOT / 'boards.yml').open('r', encoding='utf-8') as fptr:
         data = [Board(**item) for item in yaml_load(fptr, yaml_loader)]
     return data
 
 
-def DataToTable(data, tablefmt: str = "rst"):
+def BoardDataToTable(data, tablefmt: str = "rst"):
     def processConstraints(constraints):
         if constraints is None:
             return None
@@ -46,3 +47,36 @@ def DataToTable(data, tablefmt: str = "rst"):
         headers=["Board name", "Description", "FPGA", "Memory", "Flash", "Constraints"],
         tablefmt=tablefmt
     )
+
+
+@dataclass
+class FPGA:
+    Model: Union[str, List[str]]
+    Description: str
+    URL: str = None
+    Memory: str = None
+    Flash: str = None
+
+
+def ReadFPGADataFromYAML():
+    with (ROOT / 'FPGAs.yml').open('r', encoding='utf-8') as fptr:
+        data = yaml_load(fptr, yaml_loader)
+        for vendor, content in data.items():
+            data[vendor] = [FPGA(**item) for item in content]
+    return data
+
+
+def FPGADataToTable(data, tablefmt: str = "rst"):
+    return tabulate(
+        [
+            [
+                f":ref:`{vendor} <{vendor.lower().replace(' ','')}>`",
+                f"`{item.Description} <{item.URL}>`__",
+                item.Model if isinstance(item.Model, str) else ', '.join(item.Model),
+                item.Memory,
+                item.Flash
+            ] for vendor, content in data.items() for item in content
+        ],
+        headers=["Vendor", "Description", "Model", "Memory", "Flash"],
+        tablefmt=tablefmt
+    )