diff --git a/README.md b/README.md index 14be2bf1..080bd1f8 100644 --- a/README.md +++ b/README.md @@ -200,6 +200,9 @@ We have also started experimenting with the Kintex-7 parts. The aim is to eventually document all parts in the Xilinx 7-series FPGAs but we can not do this alone, **we need your help**! +## Adding a new part to an existing family + +We have written a [detailed guide](https://symbiflow.readthedocs.io/projects/prjxray/en/latest/db_dev_process/newpart.html) that walks through the process of adding a new part to an existing family. ## TODO List diff --git a/docs/db_dev_process/index.rst b/docs/db_dev_process/index.rst index c66b5d45..7b78fa07 100644 --- a/docs/db_dev_process/index.rst +++ b/docs/db_dev_process/index.rst @@ -11,4 +11,5 @@ Database Development Process fuzzers/index minitests/index parts + newpart diff --git a/docs/db_dev_process/newpart.rst b/docs/db_dev_process/newpart.rst new file mode 100644 index 00000000..73f066e5 --- /dev/null +++ b/docs/db_dev_process/newpart.rst @@ -0,0 +1,313 @@ +Guide to adding a new device to an existing family +================================================== + +This documents how to add support for a new device. The running example +is the addition of the xc7a100t device to the Artix-7 family. + +Adding a new device to an existing family is much simpler than adding a +new family, since the building blocks (tiles) are already known. There +are just more or fewer of them, arranged differently. No new fuzzers are +needed. You just need to rerun some fuzzers for the new device to +understand how the tiles are connected to each other and to IOs. + +*If you are*\ \ **just**\ \ *adding a new package for a device that is +already supported, you can skip Steps 2 through 4.* + +Note: Since this guide was written, the xc7a100t has become the primary +device in the database, not a secondary device as it was when it was +originally added. Therefore the files currently in the repo don’t match +what is described here. But if you look at the original PRs, they match +what is described in the examples here. + +The main PR from the example is +`#1313 `__. Followup +fixes for problems revealed during testing are +`#1334 `__ and +`#1336 `__. + +Step 0 +~~~~~~ + +Fork a copy of https://github.com/SymbiFlow/prjxray on GitHub (go to the +page, click “Fork” button, select your own workspace). + +Clone your fork, and make a new branch, with a name related to the new +device/package: + +:: + + git clone git@github.com:/prjxray.git + cd prjxray + git checkout -b + +Step 1 +~~~~~~ + +Follow the Project X-Ray developer setup instructions in the +`documentation `__, +up through Step 7 and choose Option 1 (invoke the +``./download-latest-db.sh`` script). This script will clone the official +prjxray-db database under ``database/``. The following steps will make +changes under this directory. You may want to put these changes on your +own fork of ``prjxray-db`` for testing. This is explained at the end, +under “Database Updates”. + +Step 2 +~~~~~~ + +Add a new settings file. Usually you will start with an existing +settings file and modify it. Assuming you’re in prjxray/, + +:: + + cp settings/.sh settings/.sh + git add settings/.sh + +Example: + +:: + + cp settings/artix7_200t.sh settings/artix7_100t.sh + git add settings/artix7_100t.sh + +Update the following values in the new settings file: + +- ``XRAY_PART`` – + Important: choose a package that is fully bonded (typically the one with + the largest number of pins). If the part that you’re actually interested + in is different (with fewer bonded pins), it will be handled later. In + the running example, the actual part of interest was the xc7a100tcsg324, + since that is on the Arty A7-100T board. But here, the xc7a100tfgg676 + part is used; the xc7a100tcsg324 is handled later. + +- ``XRAY_ROI_TILEGRID`` – modify the bounding boxes to be a tight fit on + your new part. + +- ``XRAY_IOI3_TILES`` – These tiles need special + handling for an irregularity in Xilinx 7-series FPGAs. See the + `comments `__ + in the 005 fuzzer for more information. + +- ``XRAY_PIN_00`` – this must be a clock pin. You can look at the device in the Vivado GUI + interactively (click on IOs and check their properties until you find + one with IS_CLOCK=true), or run a small clocked design in Vivado and see + which pin is assigned to ‘clk’. + +- ``XRAY_PIN_01`` and on – these should be normal data pins on the device. + +`This `__ +is what the new settings file looked like in the example. + +Source this new settings file: + +:: + + source settings/.sh + +Step 3 +~~~~~~ + +Edit the top Makefile + +- Update the Makefile by adding the new device to the `correct + list `__, + so that the Makefile generates targets for the new device (used in + Step 4). ```` is the basename of the new settings file + that you just created. + +:: + + _PARTS= + +- In our running example, we add ``artix7_100t`` to ``ARTIX_PARTS``: + +:: + + ARTIX_PARTS=artix7_200t artix7_100t + +Step 4 +~~~~~~ + +Make sure you’ve sourced your new device settings file (see the end of +step 2). Now it is time to run some fuzzers to figure out how the tiles +on your new device are connected. + +Make the following target, with ```` as above, and setting +the parallelism factor ``-j`` appropriate for the number of cores +your host has. The make job can benefit from large numbers of cores. + +:: + + make -j MAX_VIVADO_PROCESS= db-part-only- + +Again, ```` must match the base name of the new settings +file that was added. For example, + +:: + + make -j32 MAX_VIVADO_PROCESS=32 db-part-only-artix7_100t + +- It should run fuzzers 000, 001, 005, 072, 073, 074, and 075. + +- 005 will take a long time. Using multiple cores will help. + +- 074 *will fail* the first time, since it hasn’t been told to ignore + certain wires. + + - After it fails, go to the build directory + ``cd fuzzers/074-dump_all/build_`` (this is the + ``XRAY_PART`` from the new settings script; in our example, the + build directory is + ``fuzzers/074-dump_all/build_xc7a100tfgg676-1/``). + - Run + ``python3 ../analyze_errors.py --output_ignore_list > new-ignored`` + - Inspect and compare ``new-ignored`` against existing ignored wire + files in ``../ignored_wires/``. + - If it looks good, copy it to an appropriately-named file: + ``cp new-ignored ../ignored_wires/artix7/_ignored_wires.txt`` + (in our example, it is + ``../ignored_wires/artix7/xc7a100tfgg676-1_ignored_wires.txt``). + - Add it: + ``git add ../ignored_wires/artix7/_ignored_wires.txt`` + +- Return to prjxray/ directory, and clean up 074 to prepare for the + rerun: ``make -C fuzzers/074-dump-all clean`` + +- Rerun the top make command, + e.g. ``make -j32 MAX_VIVADO_PROCESS=32 db-part-only-artix7_100t`` + +Step 5 +~~~~~~ + +The next task is handling the extra parts – those not fully bonded out. +These are usually the parts you actually have on the boards you buy. + +- Add a new entry in the appropriate ‘harness’ section for any + alternative packages (typically with fewer pins, in this example, 324 + versus 676). If any ``XRAY_PIN_`` values you listed in the + settings file are not bonded out on the new part, you must specify + alternatives. In this example, we need to specify a new clock pin, + ``XRAY_PIN_00=N15``. Here, ``XRAY_PART`` is the extra part, and + ``XRAY_EQUIV_PART`` is the original, fully-bonded version: + +:: + + db-extras-artix7-harness: + +source settings/artix7.sh && \ + XRAY_PIN_00=J13 XRAY_PIN_01=J14 XRAY_PIN_02=K15 XRAY_PIN_03=K16 \ + XRAY_PART=xc7a35tftg256-1 XRAY_EQUIV_PART=xc7a50tfgg484-1 \ + $(MAKE) -C fuzzers roi_only + + +source settings/artix7_100t.sh && \ + + XRAY_PIN_00=N15 \ + + XRAY_PART=xc7a100tcsg324-1 XRAY_EQUIV_PART=xc7a100tfgg676-1 \ + + $(MAKE) -C fuzzers roi_only + +source settings/artix7_200t.sh && \ + XRAY_PIN_00=V10 XRAY_PIN_01=W10 XRAY_PIN_02=Y11 XRAY_PIN_03=Y12 \ + XRAY_PART=xc7a200tsbg484-1 XRAY_EQUIV_PART=xc7a200tffg1156-1 \ + $(MAKE) -C fuzzers roi_only + +Make the appropriate harness target (adjusting for your family): + +:: + + make -j32 db-extras-artix7-harness + +This target will make updates for the extra parts of all of the family +devices, not just your new device. + +Step 6 +~~~~~~ + +Do a spot check. + +- Check that there are new part directories in the database under the family subdirectory, for example: + +:: + + $ ll database/artix7/xc7a100* + database/artix7/xc7a100tcsg324-1: + total 19884 + drwxrwxr-x 2 tcal tcal 4096 Apr 29 08:01 ./ + drwxrwxr-x 13 tcal tcal 32768 Apr 29 08:00 ../ + -rw-rw-r-- 1 tcal tcal 10364 Apr 29 08:00 package_pins.csv + -rw-rw-r-- 1 tcal tcal 32142 Apr 29 08:01 part.json + -rw-rw-r-- 1 tcal tcal 22440 Apr 29 08:01 part.yaml + -rw-rw-r-- 1 tcal tcal 8601612 Apr 29 08:01 tileconn.json + -rw-rw-r-- 1 tcal tcal 11648042 Apr 29 08:01 tilegrid.json + + database/artix7/xc7a100tfgg676-1: + total 19892 + drwxrwxr-x 2 tcal tcal 4096 Apr 29 02:03 ./ + drwxrwxr-x 13 tcal tcal 32768 Apr 29 08:00 ../ + -rw-rw-r-- 1 tcal tcal 16645 Apr 28 22:16 package_pins.csv + -rw-rw-r-- 1 tcal tcal 32165 Apr 28 22:17 part.json + -rw-rw-r-- 1 tcal tcal 22440 Apr 28 22:17 part.yaml + -rw-rw-r-- 1 tcal tcal 8601612 Apr 29 02:03 tileconn.json + -rw-rw-r-- 1 tcal tcal 11648042 Apr 28 22:37 tilegrid.json + +In this case, the tile grid is the same size since it’s the same chip, +but the size of the package pins files differs, since there are +different numbers of bonded pins. + +Note: These changes/additions under ``database/`` do *not* get checked +in. They are in the ``prjxray-db`` repo. This spot check is to make sure +that your changes in ``prjxray`` will do the right thing when the +official database is fully rebuilt. See “Database Updates” below for +more information. + +Step 7 +~~~~~~ + +Assuming everything looks good, commit to your ``prjxray`` fork/branch. +You should have a new file under settings/, a new ignored_wires file, +and a modified Makefile (see the `initial +PR `__ +of the example for reference). + +:: + + git add Makefile settings/artix7_100t.sh + git status + git commit --signoff + +Step 8 +~~~~~~ + +Push to GitHub: + +:: + + git push origin + +Then make a pull request. Navigate to the GitHub page for your +``prjxray`` fork/branch, and click the “New pull request” button. +Making the pull request will kick off continuous integration tests. +Watch the results and fix any issues. + +Database Updates +~~~~~~~~~~~~~~~~ + +The process above (steps 4 and 5) will create some new files and modify +some existing files under database/, which is a different repo, +``prjxray-db``. + +To test these changes before the next official prjxray-db gets built +(and even before your PR on prjxray is merged), you can put these +changes on your own fork of prjxray-db, and then test them in the +context of +`symbiflow-arch-defs `__. + +To put the db updates on your own fork, create your fork of +https://github.com/SymbiFlow/prjxray-db if you haven’t already. Then +follow one of the approaches suggested in the checked solution of this +StackOverflow +`post `__. + +You are NEVER going to send a pull request on `prjxray-db`. The database is always rebuilt +from scratch. After your changes on prjxray are merged, they will +reflected in the next prjxray-db rebuild. The changes submitted to your +prjxray-db fork are only for your own testing. + +To use your new repo/branch under +symbiflow-arch-defs/third_party/prjxray-db/, you will need to change the +submodule reference to point to your fork/branch of ``prjxray-db``.