From 2dcecbd866e0aa9eb0c40a2531461043f192f431 Mon Sep 17 00:00:00 2001 From: "Rodrigo A. Melo" Date: Mon, 3 Mar 2025 21:00:18 -0300 Subject: [PATCH 01/10] Removed WARNING about a deprecated known limitation --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 2d36cdc..f780268 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,6 @@ HDL converter (between VHDL, SystemVerilog and/or Verilog), based on [GHDL](https://github.com/ghdl/ghdl), [Yosys](https://github.com/YosysHQ/yosys), [Synlig](https://github.com/chipsalliance/synlig) and the plugins [ghdl-yosys-plugin](https://github.com/ghdl/ghdl-yosys-plugin) and [yosys-slang](https://github.com/povik/yosys-slang). It relies on [Docker](https://docs.docker.com/get-docker) and [PyFPGA containers](https://github.com/PyFPGA/containers). -> Known limitation: the files must be located either under the `$HOME` directory or under the current working directory (`$PWD`) for Docker to be able to find and access them. - * `vhdl2vhdl`: converts from a newer VHDL to VHDL'93 (using `ghdl`). * `vhdl2vlog`: converts from VHDL to Verilog (backends: `ghdl` or `yosys`). * `slog2vlog`: converts from SystemVerilog to Verilog (frontends: `slang`, `synlig` or `yosys`). From a387509f644979a1c4dd7b677216ec9dd46cb185 Mon Sep 17 00:00:00 2001 From: "Rodrigo A. Melo" Date: Tue, 4 Mar 2025 16:29:33 -0300 Subject: [PATCH 02/10] Update copyright year range --- hdlconv/core.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hdlconv/core.py b/hdlconv/core.py index 63262ce..b4ed799 100644 --- a/hdlconv/core.py +++ b/hdlconv/core.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# Copyright (C) 2023 HDLconv Project +# Copyright (C) 2023-2025 HDLconv Project # # SPDX-License-Identifier: GPL-3.0-or-later # From 1995252d247efc4230a571ec30097519118b62c7 Mon Sep 17 00:00:00 2001 From: "Rodrigo A. Melo" Date: Tue, 4 Mar 2025 17:08:20 -0300 Subject: [PATCH 03/10] Add sphinx-based docs (wip), deprecated docgen --- Makefile | 4 ++- README.md | 84 ------------------------------------------- docgen.sh | 38 -------------------- docs/Makefile | 20 +++++++++++ docs/conf.py | 39 ++++++++++++++++++++ docs/images/logo.png | Bin 0 -> 13247 bytes docs/index.rst | 19 ++++++++++ docs/intro.rst | 10 ++++++ docs/scripts.rst | 17 +++++++++ docs/tutorial.rst | 4 +++ 10 files changed, 112 insertions(+), 123 deletions(-) delete mode 100644 docgen.sh create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/images/logo.png create mode 100644 docs/index.rst create mode 100644 docs/intro.rst create mode 100644 docs/scripts.rst create mode 100644 docs/tutorial.rst diff --git a/Makefile b/Makefile index 6445d20..e737d78 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ all: docs lint test docs: - bash docgen.sh + cd docs; make html lint: pycodestyle hdlconv @@ -17,5 +17,7 @@ test: clean: py3clean . + rm -fr docs/build rm -fr .pytest_cache + rm -fr `find . -name results` rm -fr `find . -name __pycache__` diff --git a/README.md b/README.md index f780268..8512b28 100644 --- a/README.md +++ b/README.md @@ -6,87 +6,3 @@ It relies on [Docker](https://docs.docker.com/get-docker) and [PyFPGA containers * `vhdl2vhdl`: converts from a newer VHDL to VHDL'93 (using `ghdl`). * `vhdl2vlog`: converts from VHDL to Verilog (backends: `ghdl` or `yosys`). * `slog2vlog`: converts from SystemVerilog to Verilog (frontends: `slang`, `synlig` or `yosys`). - -# Documentation - -``` -usage: vhdl2vhdl [-h] [-v] [--no-docker] [-g GENERIC VALUE] [-a ARCH] - [-f FILENAME] [-o PATH] -t TOPNAME - FILE[,LIBRARY] [FILE[,LIBRARY] ...] - -VHDL to VHDL - -positional arguments: - FILE[,LIBRARY] VHDL file/s (with an optional LIBRARY specification) - -optional arguments: - -h, --help show this help message and exit - -v, --version show program's version number and exit - --no-docker do not use Docker (use system tools instead) - -g GENERIC VALUE, --generic GENERIC VALUE - specify a top-level Generic (can be specified multiple - times) - -a ARCH, --arch ARCH specify a top-level Architecture - -f FILENAME, --filename FILENAME - resulting file name [.] - -o PATH, --odir PATH output directory [results] - -t TOPNAME, --top TOPNAME - specify the top-level of the design -``` - -``` -usage: vhdl2vlog [-h] [-v] [--no-docker] [--backend TOOL] [-g GENERIC VALUE] - [-a ARCH] [-f FILENAME] [-o PATH] -t TOPNAME - FILE[,LIBRARY] [FILE[,LIBRARY] ...] - -VHDL to Verilog - -positional arguments: - FILE[,LIBRARY] VHDL file/s (with an optional LIBRARY specification) - -optional arguments: - -h, --help show this help message and exit - -v, --version show program's version number and exit - --no-docker do not use Docker (use system tools instead) - --backend TOOL backend tool [ghdl] - -g GENERIC VALUE, --generic GENERIC VALUE - specify a top-level Generic (can be specified multiple - times) - -a ARCH, --arch ARCH specify a top-level Architecture - -f FILENAME, --filename FILENAME - resulting file name [.] - -o PATH, --odir PATH output directory [results] - -t TOPNAME, --top TOPNAME - specify the top-level of the design -``` - -``` -usage: slog2vlog [-h] [-v] [--no-docker] [--frontend TOOL] [-p PARAM VALUE] - [-d DEFINE VALUE] [-i PATH] [-f FILENAME] [-o PATH] -t - TOPNAME - FILE [FILE ...] - -SystemVerilog to Verilog - -positional arguments: - FILE System Verilog file/s - -optional arguments: - -h, --help show this help message and exit - -v, --version show program's version number and exit - --no-docker do not use Docker (use system tools instead) - --frontend TOOL frontend tool [slang] - -p PARAM VALUE, --param PARAM VALUE - specify a top-level Parameter (can be specified - multiple times) - -d DEFINE VALUE, --define DEFINE VALUE - specify a Define (can be specified multiple times) - -i PATH, --include PATH - specify an Include Path (can be specified multiple - times) - -f FILENAME, --filename FILENAME - resulting file name [.] - -o PATH, --odir PATH output directory [results] - -t TOPNAME, --top TOPNAME - specify the top-level of the design -``` diff --git a/docgen.sh b/docgen.sh deleted file mode 100644 index 72fc58c..0000000 --- a/docgen.sh +++ /dev/null @@ -1,38 +0,0 @@ -#!/bin/bash - -export PYTHONPATH=$(pwd) - -file="README.md" -pattern="# Documentation" - -lines=() - -while IFS= read -r line; do - if [[ "$line" =~ $pattern ]]; then - break - fi - lines+=("$line") -done < "$file" - -result=$(IFS=$'\n'; echo "${lines[*]}") -echo "$result" > $file - -vhdl2vhdl=$(python3 hdlconv/vhdl2vhdl.py -h) -vhdl2vlog=$(python3 hdlconv/vhdl2vlog.py -h) -slog2vlog=$(python3 hdlconv/slog2vlog.py -h) - -echo "" >> $file -echo "$pattern" >> $file -echo "" >> $file - -echo '```' >> $file -echo "$vhdl2vhdl" >> $file -echo '```' >> $file -echo "" >> $file -echo '```' >> $file -echo "$vhdl2vlog" >> $file -echo '```' >> $file -echo "" >> $file -echo '```' >> $file -echo "$slog2vlog" >> $file -echo '```' >> $file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..739deb0 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = build +HELPERS = $(BUILDDIR)/vhdl2vhdl $(BUILDDIR)/vhdl2vlog $(BUILDDIR)/slog2vlog + +PYTHONPATH := $(PWD)/.. +export PYTHONPATH + +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +$(HELPERS): + @mkdir -p $(@D) + @python3 ../hdlconv/$(@F).py -h > $@ + +%: Makefile $(HELPERS) + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..a53ccd8 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,39 @@ +# -*- coding: utf-8 -*- + +import sys, re +from pathlib import Path + +sys.path.insert(0, str(Path.cwd().resolve().parent)) + +# -- Project information ----------------------------------------------------- + +project = 'HDLconv' +copyright = '2023-2025, HDLconv Project' +author = 'HDLconv contributors' + +# -- General configuration --------------------------------------------------- + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.extlinks', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', +] + +autodoc_default_options = { + "members": True, + 'undoc-members': True, + 'inherited-members': True, +} + +extlinks = { + 'repositoy': ('https://github.com/PyFPGA/HDLconv/tree/main/%s', None) +} + +exclude_patterns = ['build'] + +# -- Options for HTML output ------------------------------------------------- + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['images'] diff --git a/docs/images/logo.png b/docs/images/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..78ec5b4a857beed92903b47443aef5879939aec7 GIT binary patch literal 13247 zcmXY&1ymdT)3$L4o>1IFaCeGJaMxm`c(Fo@TX9K>6pDLscPmodDOQR*6nEFcm*@X} zIVUG_cK2*{=QnfDbx+`08j5(>6xc{eNO;OhP#wf;!GBLI3?w9E=eou@#0S7fB_lT^ zBxb_@p2&&z+T=(`{GXJeGJ4*b$8RxHU&%Lfy2fRq0U@DKWNkpm6AE@7h?p>uLm966 zjZPcQLWWO8LoyCRPO6OZEq~~n#jriR4sBzG^#)&1a7AK;U&10qVog|#|EI)Evu4gn zvooXr#a}=@C15OjK40h*v)2+D|8h~Ey>hGG(Y>9dKVh8wGYe7ZY7I_-S1wHl1|FjNOb zK|AkvGGsVh-mXBaG6C=TA7`!J1^yGH6m)on^MOJWBI0{xSA5B4P%%W6j87r3N9k;@ z$r%NLD0R_D`1aXe-Rn_>hO4Iw07*vR&v#p2omN^sCP0N~e~V*JujoKbYAm2^9t)JE z&OoUQai2Qx{;#w-5&=(!5Lnwf_j`?*uEZm523e2d{^R1zg_VP9ir z>Gs8Sc`_E~`k4JG!t;7acBHJnqqLg>-lQ8z@)huGpHVyl&v0@oKFOV z>TL%j(a7zhO5Dd&}bY5A6KbigXt)&gPLvCbalPQLtC-Xdvod5C7 zJdEz7fnS`JS9gE}=^a$+qAyPpSybFi=jk)hB6n~ftIb0RTjk4Kv`E0(uX%&m zAQb@Ya>4F?$oF||YfrQ7>m-ryX%N&&nFDTP}bW|7rkaIOG&j2 z;q&%9=p&+}XLd+TT|$c&jz78DpU%mY{G49-uG0)MkijAKsi7v5PNq?bn>YSDx9@w; zUibcD+2eoOSq4o8lo5}sb$g{f)&nI{>%t5cbX+3lT|uiX+NFAxCUjrkcKD}#xZB&G z&Zl63K&(^E(2w{TN`IURG$v1<-$y1~bS`AYZir_m$lbZfRtTl5QL;8$=8(VdaAjB* zc35%#quOK*X_S``)EG7VT|;iWLSbM0DQxgX!csY**!uQlwP%hw8Aq8ce1|=~){|0^ zY@t1|BvO0u`)Vu~MtJR?kH0JN0B`E`wlNGES48Y;y-rv2(q;N#zN*f`@{~C2SpmB` zHcS1>xnrseWjT*pt$Fuh9qhOXF$_@Q45|SKeE9c|o^yM;=ckp2PO^_){kz!2Y%tMj zc@7d{*c=LVp zI9X03<}jSxHWi<>9ZRoG<}?v)B;w@?Uc;pn`nB&b&@{Ox%Z?{ZL_)$u6F$9#@zXn3 zyYPD6zR%{OegiNyP~gd=fMu>#YuVq&kQBqvh2#+Ut=6c{8aSpxhGl=YY1L*s#`Q_JW!Q78T#*jH>VZ1cM=K*!3R|+5|?V&%QO$umxN8` zak--&56lZZ?8*F~;6Tnn`G`2ZdUAeSku1d)Vhmr)%r^=sB^`NE1G+KtCkj=C%M_n= zH79TWk|APCyHmj{D6=3AkuZYeFo96oJ6YnJT!TII+o&@io z%6P<2dm&A4^}lyzGNn^Jv8)KFwok@|tWS+b*bc>Q9Q^dV{YJm*XY;r7Q@(M>u;=OO*hnJlmI#Jiu6FB968jszkO{mT$OiJTV@-FuCB{cM50Uer zy*-#IUyCA@LN0$9b6>(MfcHX_zlo5;YCVG7l_Nq{8Xf04Mr&t>hi=yb1Cz3>;`2?C zEC^25h;s53hXwE;LlFu&v^#udJDeopO;*geE}s5_5FQ#%S6=e6_urFq`P%thb&A=J zH2xBw`>b_*uCSZRVbe=Cf9+59ps6NI49(+MHMBNZnK0rzfSYQLK?n<3K;%_d%nXuld`& z&-1q0``|=Tiumh+BDDE-?d%z0QSl?HmH`Cegw@!kZx}Npu^bUHvO?KqB!2KN2;qaGjh#BezMkC z?f9K!IXS_aMF6u)y3&+m4#E?Mo8%@DYa}?C7>@+S3`Ht)%!j)n;STIr?(QcE8S006A}E zg$UPtP=yQI4m0?4!X50OP_)rx&J6E2^mF}X!3OK+N19nx3Nl7B+sGWvEqt4`TE6y=a#)8yBxsqy!lI55`8vab%k&@Z zids>oykV~-ziHqRL!9gi@JqIQ0+V`C&ztFt!v$H$a*$#S#S9Hb{F0$2#EXf};%tot1;86Ksg`jCFx<_4T z;BC5AHQb$WFMrri4CrxdG@Ue{cMSd$H*|eC*V$WZb{Ob>&XL*mAfrKdHs>M*_rg^m zpb;l?EbRAU4|85>I#!SUVEi)8$cK1vdQ`8UeMu+J*|*#`3rG^A;Th~*y5K%pX`wgJ z7{MpDTehOXAC>jC*{9RH$)}f9jHOx#_V2Wh)BPF26@S(&Bb(|htsX6JDMCY3R}&qY zK~gWM`v5N$jf0Wb0vQxwuHQ)Htl|lgvsr`GSb~zVyeHdYm-xN~P)%d`e>~-)oG!|| z6L*~D07hXr{+4FqOz(|i8jNeK)q>9!4Ttpvf0_Y7FvW#D4cQcu$?^)H?@cj~t_r{l z43RkH=4xKq^EqUJUj6v!BxNFAN8RQ%$4kNNoN7Ct3(;9mc^6Qs{2g0DmiIAiTgzr7 zQ5h+qhDPQ&3nv~31TIKhCY#EKg!J*hIK3B3iMA^4xovr>)+tosko4nlu;56N?MJ@0 zFu-vOqa##(`bAhG8>MxpsW7oVfXJ1Ww)l}Rp*ZmkugZqR8vg{|<8CY&)Yt5zF8uTJ zGJTF@?er)osYgf|vLfKm0d0RK{cKT>5ne=zlqQC<_^`}Yn!Mrgf^Lf;POHd08z(;V zKH#a38{f%r2)pxbZ+;Zz#&`_-(Jq(%g4HlOma4OEq0#`?i{H|E%Hm{M_;CGZ(i=12 zAaERAm9g>ZdKnoTdI=kl5Bzui<~){H|6ZIF?6&jE2XsmrOKa}sVrs)(F#J8+lH3&! zn@)WBu)32Ax6i=@n<9d^`EqA$+WmtLGK$aRcqz%igYJb$Plafmc+jDAr2&>axtRN& z7IX0sqMm=L19{(Xr%a6O9xAAA4M=3q*Sd=E+(tXhw!r;f+{&7Rg#7vJ9q)2g&Sh3VB5ayOCJVq*0T6 z&^xbmMt6fX-=mAPkJ>C&S=HoZz_QsMTf{C8-w9Q%zW6WvH_7utc0kYPj?I`hQzDL28iXh09x z9F#(lu(`Rm$=WzU0T<>cP70n?yWcHe#V`bs%9)O3P4OVHFx1 zp5Tn4fqbAr`m%6o3P}b-`bk`;GzTrf_BIy7JA3IUtx99VC~0C_K>v%j{e8N0$Okte zvZJv2*S6a=lC)uY(t|v&JnCUui9W8JP7%_?3Sl}Ae0nGwUayWP{H7@hbVE3yLJoiI zm|piy^ZN8hs<8AZG872Ny6gV$!d*Bpmu&|=>@&~i%3+?TQDxX$g<{@5X;6F zP9^1g(sy$Nd-k4c=&gdv=1B2h1&0OwxK_5vryBjf0z`aM)Qv`-9g%v05x@vK8TnJ9 zUo5Dci`0YnirZ{ih9#Zf_1#@{=QAjO2F)lqRYAcEf4t(1P{;wg1n308J#Ks#Vq>}A zbv%WBV^rl59Lc7W;NYm>TpVDNLZ25kUy9iodd`ObGOLSvAC_gDIf0)GS}aL?PUQAiTNDV-1=pIVzb1&I$|fP zf0}&#S8X9Yw)V#P;*Y9zzvkzK4bD#Z$7{#giqbkn3)Q@zi3r4h@P?moqjkWO3Pe6F z2&|mu(tbYR39cPW#pBq=DP1not(2ECs5QeBdOm!izw>WtUJLLe8VUpLBj2}Wki}UD z#I<-F&i?)={yli6n#su){!JuuU%b@<-$eA--t^%%{qtc%BA3xf!;`QH)Kn~vwfK7Z zsu8Zn0177NR}@j`;N>f*QdUcZq=o*H{)UAXrj!_eW%RYraaR-eK@3a&ONwQ4RrdQ* zzV^TF*=kHd+mwa_8|+Kh>t0}Oa;?frMZ}^iG7Pa$@)W*nkbDO2*8)d;&8+S ztf{O+P9tOPBP8v>#DSy5v7$CD%7e`*5%BtAM3 zVPU6Z2re_a<%ZZZQ?y3DJ#cD$zwBMx@Kvf(9PEZv5>pJ`6`M5O=eH~LP9%0gxkwQ@ zAOJ#Mq{fKavJs|k8~Vej!;PVVXiIu5Dd2{Dc;>1m6=iXu{;0M??xaLYDMN@Ace2UC zIx!Fo6|g*iT@;7KLA7e!UTxB>afBMW^3&cCC(N+Ri-8Xg_27^}h?LZYt$AhZ0X-0} z#HW|lxABECnw#DrZhUzr8u-tks~-NUs(3IN19JOQ%}5$zw`G==0uZ z{17#cwgD!4B92 zMY}FBs7z-B0er13IYnS-gmXO~A9aJ4l_i}XLxpemiRixD&Nl=f?Q!jTs2D0lPVyu2 z5Q+8FH>+|8=xPWT0I=wdz$2mxkBr<+3EYzXTWd9Vu`c0tj!m;#_1XLC40);L>HW>z zZ&qANwUMr(LYQAL55D1KY!EGMLr(aF6^_Qq2Ta3;=HY8k5Qxt0W|iC4R7Nq^Mc%%> zCFRsBiNo3oXZajv-01MynZ!DeJ4Oj@HBM<#w}=Eq0|LIH*P#X9luF0EHt#~3ZLrsk zc_%43(Q$CAds78FJCS@0)PJEEZqGA2# z^)6%}-7t3a!+7EtTy1f6{##||%lN9_sRUwmr&|!bcFmq|j^Ac8Sp6Ly6ZA8^_B}r` zGN(_5nzdNNy;iajy&K{zxmF|_Xtz7+g{`ZM>M=(1vV@Lx0KZx{{| zN2}IQG4WrW8h>^s1=qUJt-knO#l0237aq;5kK2%6vCtVDIU0{Cw?=B8rW)8BXdFT# zhq;!8%SVyy-(+pCeVDJ2N%@5Uz_lPo6}zHNhZ#0SD>DS2pJ=>x^ z(s+sJnUTBJ;fW$&`{Nqty*Eh@%#P4%akY`-YfOZHDfB#EbXG>w%AkxdEmTW{8$719RBDkA6EeHs2QWJz| zWZofv7E;~0*VPRD2)-&a+WT)4AysfUOpTZi9`q}i1{dD9C}~U->g24DR?Za2zRF8s zMQm(6p2n{TRlJUXhR~$JNR+gaU~s8rVSl#Q4duSJ(h#M;q{MR40&(_C8MF^>aPMNF z6#bxI2>VDx$V$--5aW3u#%>r%agnZvNmf`^?Fl8cHOX2z%1#7P@B+$fRw*VOBn1E$+s`CFh<((R-B2AQ@^B2H&eun;27=8ok&i;R~j`L30qUVK&q#cc&$>XEatj@|hpe^0*4@05m` z^uJ6l4AS8KFygniY?`ned3CJBEWVDKhY)B>%(6`}Hdp zEopwdt1MoSwZLEq>Cjn$%kz>;XKlKmV{06YSGDgNy`2$w<}0qlblG!WJZ?<(9o_oB zz~a-cKCRFoFc%nrsr~HmiJ=hm*8rQ3c2%h{bug@MMR9kqJQpi6IsZQTE76UeR+7~? z0(}>UH7_KK&o`C3yHG*+K`B>}37lx0)y|wsPvp#GoG-!$Z!dZ6L<$f30L_a*2ko~3 z(^kjD+8A{43)SP4(Y%)$kY?Q(Mxv;1U2x(rP?T|ho-3RXvgk#rwe4gf?#_YOC?u~u zimdaDE1w0`Gj3lHAwUe1BbeW|y6;yS!ppt^yj8(6QEFE~6asb#O2r5yAj{!>YtEcz zMx-1tbAY1UcRd9r`ZAoxU%XeVwYHGq^F9uaDR;S;I>HFPRzh26(6HVNq@g6ltA_WD zC;4VS(-8rS&$trcHSP8fl_DBj4kaW@8Pa*!2)#@8< zdVI*%$}U5Fab&iPGp-@rP?3-EE=$QL7_uWj1VFYPvB@{J zMPY-Vt$vS(IGEE9$V)S&BRzW1FjYzLbXS~K!xO24Fg0cbfywXiY z4VE6!Z+~@lzgE3AmJV$}U^!GwJc=v4M1@rXI^4&_@1}jpzo0Z02$d}X^&yzq-Ugz!M-h@rkKYc82j1)tjdUYQ z`xAxIQZ%7Ebfm(kucub=Zbl|`T0LYmXufBu|W#h=K zws~=r4@%s=mqbmTrQ3VeuY8V%07OdBYcFTL1aHssw$O1%#1R@bFC9@w+^A{X6SC7h zba}~ZjpHu3qCRf-m|dP&o>)+N^xeMsYGsn=U&vPbCOU6UXyOC%G6Ze-6$Rt4sMO)FIa9we{^T z_8Z8JTL7Ky#f%udF`gyHD$d7(L1%yi@*CL<|83nBgbWt=!uG37zr0HCwq`87S)_c% zC%W`HNw_-G>OH=bwU@I(T?6;FsM6{Y5^kIt4!%a+VNfrrX-f zY0!;c31u1oKjJf$0RsN`e4IyUwNPi%|D20fF-FF3i#z(RhUd}4kp0GH@AN2KfE;%^ zgh%R_*9gl^d+*JW(;ZjwOMaifSs#|Ta0qly+a+8{DPD+3^;dY9pzj$!RLQO+?SrEuvDjs8S&Y{i)PnD z)HjId@Y>%v=|!}iv+d)R{VsD84*x7bM-|4s?W3LuR>q>-5CC z#k7o}YYai4*P2kQRAey9oJ8s z0g#ijhnMu2SjfV#fK=qzFB63o!|pBrQe0ENK` zhcAR;jb;5=xm_4MzodPDx>)F^!h%uh&DuQ2c(cL^8&p%c{!Na5Sd@_0!UC1(6pm0- za4U#A7^Pwb;ak`u@V#tI_k%c&cDR^@W%q6x|NFXkodGMnA{1(}5VRON07T7uSvpl) zTU(i4t$i<3g#I8jti@86fTUx~>jvU0#_a@@*`=fFsZQvf93Lmnq`I=6Nu00h}VE z3_>OY%jw6m&X|L2C$Z{e!?7t@(lO~ZVA=Es7;J(`6GYOBobH_$AJ8n-Gd$u#p ziHp|I$(f;RD1OVMjMh(R@cD23QHHr8i=#Xt>Zvq>^kEb-Bj3@HAKPyW^*XiLxvEZR&f{+YBFq7%=GY_ zLek&+J=ynbO2mC0GK0+=^73lHgiteD--!kGoPYjPqHU@9solF0A|xHcQ`<{(gFY9+ z@e7fax6-1vY{On#_Q5p7S2nJwb>neJI7(vD!1beXoB%!qfNch96JF+|2IPJ2Ge#8Nw(cf$&;+G_H}=0rP$o#x}lGGFWZ518rC&m47!Vp{&xMC{e~ z$p}VRMspRWTn?GJlpqFomutju{6c`{%*}}6Z!g@U>{;IL8I3XtKL-y*6)zkG;LV4Y z1X2%9DnLzuViPlE`l?t!%JnAa72~IO#NZy@fa{qzn^Z@XOKn~*V~+cPgrNN)gzLP0 zrUyf-_FG_~--u_RjUvi(Ij1||di2;!IocfVq#pc1x30rv*=U7of%R$m$EQ3wR678$ zO<;@4N%`_}LaH8-RAG3rh*)=&(M(N^4I_#+=t5;bGmLBP75*f9MeeLFK0X_y(N!FyLHu;pw2BA=EEK9=q~$odWK~8OJk``I^D< z$W7+UmR{1E3d2uXWd!^+97-Y*C9D0215*>y?oGT?te3Fp{KzY@M2en8^h`Bx;_`F5 zBz^EJ?L^1Zh3a`AyKJI%ksA5bD3gV3qC(HFYzZ;hwjWqThimj|cded>v&Vk*w~oqj zu1eVk5>ZT)`TAm0-op;AFm{ph$Dt?rwk6~$t7x(l9 zG|r2oF0~?&)n_Bd0^SSg?co=p!^hlgcu6?kB>Y@cYs&&+UV2}xONzBRaxPH{WxN&n zq;#2ya4U@5MI|5h7-~`ZUAWRtDh!G9u*-Y;G^Pk>CEXV>cDsU6<=5#r9<2|$6X_8A zSyXSehCy>!<&$LtOp$=LhQGZ}tkw%vtjSN}@pe{l#qB?P+!&$x!3+!we@b=3?=-T- z_xCE)Qh9Bz}?_M;?Sd)Iz|=jCv_kDTFhj@j?*6>0bZ5VoQj6<0&j&UdohGM+<>w;*`wL4Bm*d4o%PMlzrTIt7yu@%gby_WLm3aN{ zs<&cOv3;S6>+B6{Pk5l6ov{q+9x5L5ATnemgc-Wiz)pAdH;E3lmc2wOs7zophx%x8 zr|@WKywTFTpPJ8lh%UlN$(>Op@uSn&9%o)&USCtJ5&OSY)Lo|h13({-9nY$JL_mEi8{wskB^CEpN#z#{2IxsvH-3sw63^6%wvhJKQD_R2*NZcw9Y(_yg|P584a)Vqzb2u^Jc+-~$nw&`sXGVN5I zhw!XSo+=Z9w0#hQAfdfQDgj9y-x&=%XUud@zT52~q3r(0j8NElmx<&#Vn#CI>X zTP+v5_|9V@Z?-I6Zai*u8q`6Cb?dw+uX!%ra^zfMNeQqe<`8H0I`-f5<7tSNxanUf zJ$`SQ)Oj8=5~hf^bZWS7ySj;Wt+FjQdcrFZ({{2>AFb_v7r;fTW*iml;k62;q>nYz z9=tb7`qsr7SycLn+8`$@8^-hB#KMUQF^t$;nucGF5L|`q937ZiDlg&v*;Hm=hQU z8{fWyrlJY;=Q-6{9NdKGj^O`$uY#HR!;t~SSGI3i5L{{WllJQq{f0qUltnbCw#pup z160&3vwi*X{LDaT_faVJl#U{-XQ9i)8?4q614sU#cAu8!*dzyI69*P85A>CwEH17i zWic&x0(mB4jmWTcFf4s7SB)KgLdm_id1Iqa=4D%re`>mL4L)&682VkqP=XA;!bVlw&iC9F#!6!gux8Uyn1Ui33^L? z3n&!Ygcxc(^ovOidK2`dJ_(R;Y4sFW!QztCSq;&Q@jcc4I@Vk_W6$1kdmu9Qt3LfV4{Q((kqc0 zzJ*DmIVhWrM0Cjm2d5G*6;hMY0QBJRC9Mo3E)asArVm$HWv*gjErI{4IS$7025+DL zJ>qzA2BLnDgW<+y01)me$>0=R##T8|NzD#EaYu_3Ou;F5jkzv>BW97}Bn8k7C#V0- z`wHqkJZhqpim>M%G&tUC-MahZB|@-qxEYSuF#P)f#vus0Xh|3@{riv9!^#nc7SGoL1ZKC(c6G8EgECC+!TY z>f-Mj?58QVY;J@fdY0M4;39F2f?Ef5_f$x|eA}pHU<>%}JF8v#L>i_!0%6jA<4U$+-q#2Eys;(NwTN-5wm*2s|AK@1 zBL5KWgj;Eb!%OTu+G5|6YCaubi3v<*bIAWL?i;`MwCFno98-(pE>sS46J5n$`3z~8qqFR=mr9G1Z zf%H3Oy}i9z26f7vf{be7N+QYW`xV|`D6uCF(V>HR=fb#(8W2ohf~FkA-AbyNK!2!EEQBSR|_QVP+CLNwxh z{mv~MU*B18iUEkSS3kzj5ivFLo|{i?d_<%Q9QrcE>Vv!SG@wP|YpOz5H^lrAj6Y?= zD@ZLC+0krkxhvM*j%gtvp9XA)X78yx^t({irEm-aTpNhyIXC}5bzu;uY?Y}nNdyjK z7XD0_75&bSG0bOcAV$EB;+$fa=_VBy!vZ6m&Syq6KE;-EUo7kgLP-!b+-xqjdN|s* zn-CYx{`%71C8>3ouAC~q^`G^FWs#>h2eJ*tz%vaXptq!oj~dGtxpT^_2qren33($ohF!6k(E=gypv3EBg^;ioMAUr+?)2%>Du@AJg`nN_diSYT z7a0U9_HgJH{UUjAYGP9?<^QlK04yQGr^Jd4L-q_5b@^d3SJ7iaUlzm@YX4^bJFuXc zjsQ~L6Lv@pg_lwF^!Zmwg|Su}O_|JbY$00Gyck4$BXovXlgrw3#02g&Kce>sbaScs z1piDEWS@v41k`H8p}B;^@0}{Lm@Il&MZ8XyX_go!D$MUNvPc=kU1TAB#xe+2!6g3s z*v`uMtwtF$6nEI^zj3E&(%4+sbqM6HjV&d7PkrX89V`B984J`ki2>J+$m&^cuumW} zfmZtr#nEe6m^OT8hN6_c=fDeMZt7o(iTCD0Q*KKb8MMP`_=?cl!eWc5hKHe^xeFd+ zgy0AlJC4L4WCyifi(^nDajgbAcR-9JVpY(5Pc!F`sURtcC$z^AC>xnFqB|u8F_Ab~ z%!Z-J4SyG63i;hjPQqRBX?DpbDX7IB_k6O69L)ohLvK1&CO#Zq8F2n(tS7oLBn*f0 zwH4BdPf@V!?Y1N0 z$)Kf;7{Lpl?|E|=m})f(+W8MLNCiBJbR_lb@}k!o#HC_n@L0&Qn}Hjv=OJd7PIsl9O zuP@pdo8%*mM}?{>W?@^%VPSFf7vrydmA*lS|GhEu*%nZdIbuFJ)+n`|6B@KekflZR z)$W$Q@-;4R^u^@)=>Ly1heXhbH_^x=zxTYL(mrEV{u#IcA^wqrq%5xit&%kl`F~jG B_RjzS literal 0 HcmV?d00001 diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..6a78fd1 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,19 @@ +HDLconv's documentation +======================= + +.. image:: images/logo.png + :width: 200 px + :align: center + :target: https://github.com/PyFPGA/HDLconv + +.. toctree:: + + intro + tutorial + scripts + +.. |timestamp| date:: %Y-%m-%d %H:%M (%Z) + +.. note:: + + Documentation generated on |timestamp|. diff --git a/docs/intro.rst b/docs/intro.rst new file mode 100644 index 0000000..759c47a --- /dev/null +++ b/docs/intro.rst @@ -0,0 +1,10 @@ +Introduction +============ + +HDL converter (between VHDL, SystemVerilog and/or Verilog), based on `GHDL `_, `Yosys `_, `Synlig `_ and the plugins `ghdl-yosys-plugin `_ and `yosys-slang `_. + +It relies on `Docker `_ and `PyFPGA containers `_. + +* ``vhdl2vhdl``: converts from a newer VHDL to VHDL'93 (using ``ghdl``). +* ``vhdl2vlog``: converts from VHDL to Verilog (backends: ``ghdl`` or ``yosys``). +* ``slog2vlog``: converts from SystemVerilog to Verilog (frontends: ``slang``, ``synlig`` or ``yosys``). diff --git a/docs/scripts.rst b/docs/scripts.rst new file mode 100644 index 0000000..4227d8b --- /dev/null +++ b/docs/scripts.rst @@ -0,0 +1,17 @@ +Scripts reference +================= + +vhdl2vhdl +--------- + +.. literalinclude:: build/vhdl2vhdl + +vhdl2vlog +--------- + +.. literalinclude:: build/vhdl2vlog + +slog2vlog +--------- + +.. literalinclude:: build/slog2vlog diff --git a/docs/tutorial.rst b/docs/tutorial.rst new file mode 100644 index 0000000..f436391 --- /dev/null +++ b/docs/tutorial.rst @@ -0,0 +1,4 @@ +Tutorial +======== + +Coming soon. From 1fb7e5825a591ff2007218f07ae7aacd1d3e848d Mon Sep 17 00:00:00 2001 From: "Rodrigo A. Melo" Date: Tue, 4 Mar 2025 17:12:03 -0300 Subject: [PATCH 04/10] ci: add to publish docs into GitHub pages --- .github/workflows/docs.yml | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..ab7debf --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,26 @@ +name: 'docs' + +on: + push: + paths: + - 'docs/**' + - 'hdlconv/**' + branches: + - main + - dev + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + - name: Install dependencies + run: pip install . && pip install sphinx sphinx-rtd-theme + - name: Build documentation + run: make docs + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/build/html From debd4837ec58c7512364b68f0556f194b1ac24e1 Mon Sep 17 00:00:00 2001 From: "Rodrigo A. Melo" Date: Tue, 4 Mar 2025 17:58:43 -0300 Subject: [PATCH 05/10] docs: intro updated --- docs/intro.rst | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/docs/intro.rst b/docs/intro.rst index 759c47a..864f6b5 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -1,10 +1,29 @@ Introduction ============ -HDL converter (between VHDL, SystemVerilog and/or Verilog), based on `GHDL `_, `Yosys `_, `Synlig `_ and the plugins `ghdl-yosys-plugin `_ and `yosys-slang `_. +HDL converter provides a set of command-line utilities for converting between VHDL, SystemVerilog, and Verilog. +Those, gathers files and options, then orchestrates the execution of the following tools - either separately or in combination when required. -It relies on `Docker `_ and `PyFPGA containers `_. +* `GHDL `_ +* `Yosys `_ +* `Synlig `_ +* `ghdl-yosys-plugin `_ +* `yosys-slang `_ -* ``vhdl2vhdl``: converts from a newer VHDL to VHDL'93 (using ``ghdl``). -* ``vhdl2vlog``: converts from VHDL to Verilog (backends: ``ghdl`` or ``yosys``). -* ``slog2vlog``: converts from SystemVerilog to Verilog (frontends: ``slang``, ``synlig`` or ``yosys``). +To avoid the need to install multiple tools, it relies on `Docker `_ and `PyFPGA containers `_. + +Command-line utilities +---------------------- + +* ``vhdl2vhdl``: converts from a newer VHDL to VHDL'93. + * Solved using ``ghdl``. +* ``vhdl2vlog``: converts from VHDL to Verilog. This has two alternatives: + * Purely ``ghdl`` (**default**). + * Uses ``ghdl-yosys-plugin`` as frontend and ``yosys`` as backend. +* ``slog2vlog``: converts from SystemVerilog to Verilog. This has three alternatives: + * Uses ``yosys-slang`` as frontend and ``yosys`` as backend (**default**). + * Purely ``synlig`` (based on ``Surelog`` and ``yosys``). + * Purely ``yosys`` (simpler SV support, but could be sufficient in some cases). + +.. note:: + Multiple alternatives are provided so you can try different options if one does not work. From b15405184fea0016c330381dc91cde07379e9658 Mon Sep 17 00:00:00 2001 From: "Rodrigo A. Melo" Date: Tue, 4 Mar 2025 22:48:46 -0300 Subject: [PATCH 06/10] docs: add installation and basic sections to the tutorial --- docs/tutorial.rst | 57 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/docs/tutorial.rst b/docs/tutorial.rst index f436391..c3e6b56 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -1,4 +1,59 @@ Tutorial ======== -Coming soon. +Installation +------------ + +HDLconv can be installed from PyPi with: + +.. code-block:: bash + + pip install hdlconv + +Docker should be installed and able to run as a normal user. +Instructions for Linux `here `_. + +.. note:: + + HDLconv relies on containers that are based on Linux systems. + +.. hint:: + + Do you prefer to use tools installed on your system instead? Use the ``--no-docker`` option. + +Basic +----- + +Mandatory arguments are the name of the top-level module/entity and at least one HDL file: + +.. code-block:: bash + + vhdl2vhdl --top Counter counter.vhdl + vhdl2vlog --top Counter counter.vhdl + slog2vlog --top Counter counter.sv + +Any of these commands create the ``results`` directory, containing three files: + +* ``counter.log``: contains ``STDOUT`` and ``STDERR`` messages from the underlying tool, mainly useful for debugging errors. +* ``counter.sh``: the bash script executed under the hood. +* ``counter.v[hdl]``: the resulting converted HDL file. + +.. note:: + + The basename of the resulting file is, by default, the top-level name in lowercase. + +.. hint:: + + Are HDLconv options not enough for you? You can always manually customize and run the resulting bash script ;-) + +The output directory and basename for the resulting files can be specified as follows: + +.. code-block:: bash + + vhdl2vhdl --top Counter --odir newdir --filename newfile.vhdl counter.vhdl + +Advanced +-------- + +Alternatives +------------ From 7ff7bb1822f01ab2beca1086a656536a069d0b3a Mon Sep 17 00:00:00 2001 From: "Rodrigo A. Melo" Date: Tue, 4 Mar 2025 22:52:44 -0300 Subject: [PATCH 07/10] Fix issue when running from a directory different than the location of source files --- hdlconv/templates/docker.jinja | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hdlconv/templates/docker.jinja b/hdlconv/templates/docker.jinja index 8c4de64..4c17d5f 100644 --- a/hdlconv/templates/docker.jinja +++ b/hdlconv/templates/docker.jinja @@ -1,4 +1,4 @@ {% if docker %} CONTAINER="ghcr.io/pyfpga/synthesis" -DOCKER="docker run --rm{% for volume in volumes %} -v {{ volume }}:{{ volume }}{% endfor %} -w $PWD --user $(id -u):$(id -g) $CONTAINER" +DOCKER="docker run --rm{% for volume in volumes %} -v {{ volume }}:{{ volume }}{% endfor %} -v $PWD:$PWD -w $PWD --user $(id -u):$(id -g) $CONTAINER" {% endif %} From dce4305ddf6265e17bec14d80689cbc2bc94cf26 Mon Sep 17 00:00:00 2001 From: "Rodrigo A. Melo" Date: Tue, 4 Mar 2025 22:53:01 -0300 Subject: [PATCH 08/10] Bump project version to 0.3.0 --- hdlconv/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hdlconv/__init__.py b/hdlconv/__init__.py index ef224bb..17cf4ca 100644 --- a/hdlconv/__init__.py +++ b/hdlconv/__init__.py @@ -1,3 +1,3 @@ """hdlconv version""" -__version__ = '0.2.0' +__version__ = '0.3.0' From 20290569663ba8bec084b9dd556e3412cabd22d9 Mon Sep 17 00:00:00 2001 From: "Rodrigo A. Melo" Date: Tue, 4 Mar 2025 23:34:01 -0300 Subject: [PATCH 09/10] Add a test case to exercise the recent fix --- tests/run.sh | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tests/run.sh b/tests/run.sh index c5cd66b..60e4943 100644 --- a/tests/run.sh +++ b/tests/run.sh @@ -84,3 +84,8 @@ cp hdl/vhdl/top.vhdl /tmp python3 ../hdlconv/vhdl2vhdl.py --filename convD.vhdl \ --generic FREQ 10000000 --generic SECS 1 --arch Arch --top Top \ hdl/vhdl/blink.vhdl,blink_lib hdl/vhdl/blink_pkg.vhdl,blink_lib /tmp/top.vhdl + +HDLCONVDIR=$PWD/.. + +cd /tmp && python3 $HDLCONVDIR/hdlconv/vhdl2vhdl.py --filename convE.vhdl \ + --top Counter $HDLCONVDIR/tests/hdl/vhdl/counter.vhdl From 9f35a2bf62911dad44c6d15a3fa8e817fadbc72a Mon Sep 17 00:00:00 2001 From: "Rodrigo A. Melo" Date: Tue, 4 Mar 2025 23:34:20 -0300 Subject: [PATCH 10/10] docs: finished first version of the tutorial --- docs/tutorial.rst | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/tutorial.rst b/docs/tutorial.rst index c3e6b56..34d1482 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -55,5 +55,45 @@ The output directory and basename for the resulting files can be specified as fo Advanced -------- +When the input files are VHDL, libraries can be specified by adding a semicolon after the file path: + +.. code-block:: bash + + vhdl2vhdl -top Top blink.vhdl,blink_lib blink_pkg.vhdl,blink_lib top.vhdl + +While generics values and the desired architecture are specified as follows: + +.. code-block:: bash + + vhdl2vlog --generic FREQ 10000000 --generic SECS 1 --arch Arch --top Counter counter.vhdl + +For SystemVerilog inputs, you can specify parameters values, defines, and directories to be included: + +.. code-block:: bash + + slog2vlog --param FREQ 10000000 --param SECS 1 --define DEFINE1 1 --define DEFINE2 1 \ + --include hdl/slog/include1 --include hdl/slog/include2 --top Counter counter.sv + Alternatives ------------ + +The ``vhdl2vhdl`` script is solved using only ``ghdl``, but others provide more than one alternative, where frontend or backend tools are modified. + +By default, ``vhdl2vlog`` uses only ``ghdl``, but the combination of ``ghdl-yosys-plugin`` and ``yosys`` can be used instead, specifying the desired backend: + +.. code-block:: bash + + vhdl2vlog --backend yosys --top Counter counter.vhdl + +By default, ``slog2vlog`` uses the combination of ``yosys-slang`` and ``yosys``, referred to as ``slang`` for simplicity, but an alternative frontend can be specified. +One alternative is to use ``synlig``, a synthesizer based on ``surelog`` and ``yosys``, as follows: + +.. code-block:: bash + + slog2vlog --frontend synlig --top Counter counter.sv + +The other option is to simply use ``yosys``, which has simpler SystemVerilog support but could be sufficient in some cases: + +.. code-block:: bash + + slog2vlog --frontend yosys --top Counter counter.sv