diff --git a/COPYING.md b/COPYING.md new file mode 100644 index 00000000..4edf77dc --- /dev/null +++ b/COPYING.md @@ -0,0 +1,16 @@ +This package is released under the +[GPL V3](https://www.gnu.org/licenses/gpl-3.0.html), +all files contain the disclaimer: + + This program is free software; you may redistribute and/or modify it under + the terms of the GNU General Public License as published by the Free + Software Foundation, either version 2 of the License, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY, without even the implied warranty of MERCHANTABILITY + or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + for complete details. + +The full text of the GPL licenses is in this directory as +[License.txt](License.txt). diff --git a/COPYING.txt b/COPYING.txt deleted file mode 100644 index bfaac45e..00000000 --- a/COPYING.txt +++ /dev/null @@ -1,16 +0,0 @@ -This package is released under the GPL V2 or higher, all files -contain the disclaimer: - - This program is free software; you may redistribute and/or modify it under - the terms of the GNU General Public License as published by the Free - Software Foundation, either version 2 of the License, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY, without even the implied warranty of MERCHANTABILITY - or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - for complete details. - -The full text of the GPL licenses is in this directory as - LICENSE_gpl_v2.txt - LICENSE_gpl_v3.txt diff --git a/INSTALL.txt b/INSTALL.txt deleted file mode 100644 index 6a43dcdf..00000000 --- a/INSTALL.txt +++ /dev/null @@ -1,7 +0,0 @@ -# $Id: INSTALL.txt 317 2010-07-22 19:36:56Z mueller $ - -For project installation notes see - doc/INSTALL.txt - -For further release and usage notes see - doc/README.txt diff --git a/README.md b/README.md index d1ca67d0..a37e721d 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,14 @@ Digilent Arty, Basys3, Nexys4, Nexys3, Nexys2 and S3board boards and boots 5th Edition UNIX and 2.11BSD UNIX. For more information look into: -* [w11 home page](https://wfjm.github.io/home/w11/) +- [w11 home page](https://wfjm.github.io/home/w11/) +- [change log](doc/CHANGELOG.md) +- [installation notes](doc/INSTALL.md) +- [short description of the directory layout](https://wfjm.github.io/home/w11/impl/dirlayout.html) +- [guide to run test benches](doc/w11a_tb_guide.md) +- [guide to boot operation systems](doc/w11a_os_guide.md) +- [known issues generel](doc/README_known_issues.md) +- [known issues w11a CPU](doc/w11a_known_issues.md) ### Note on freecores/w11 The [freecores team](http://freecores.github.io/) created in 2014 a diff --git a/doc/README-w11a_V.50-w11a_V0.60.txt b/doc/CHANGELOG-w11a_V0.50-w11a_V0.60.md similarity index 57% rename from doc/README-w11a_V.50-w11a_V0.60.txt rename to doc/CHANGELOG-w11a_V0.50-w11a_V0.60.md index c66add0f..de9e4df3 100644 --- a/doc/README-w11a_V.50-w11a_V0.60.txt +++ b/doc/CHANGELOG-w11a_V0.50-w11a_V0.60.md @@ -1,129 +1,79 @@ -$Id: README-w11a_V.50-w11a_V0.60.txt 578 2014-08-05 21:28:19Z mueller $ +# Changelog: w11a_V0.50 -> w11a_V0.60 -Release notes for w11a +### Release highlights +- revised ibus protocol V2 + (in [w11a_V0.51](#user-content-w11a_V0.51)) +- revised rbus protocol V3 + (in [w11a_V0.52](#user-content-w11a_V0.52)) +- backend server rewritten in C++ and Tcl + (in [w11a_V0.53](#user-content-w11a_V0.53) + and [w11a_V0.562](#user-content-w11a_V0.562)) +- add Nexys3 port of w11a + (in [w11a_V0.54](#user-content-w11a_V0.54)) +- add Cypress FX2 support + (in [w11a_V0.56](#user-content-w11a_V0.56) + and [w11a_V0.57](#user-content-w11a_V0.57)) +- added LP11,PC11 support + (in [w11a_V0.58](#user-content-w11a_V0.58)) +- reference system now ISE 14.7 and Ubuntu 12.04 64 bit, ghdl 0.31 +- many code cleanups; use `numeric_std` +- many documentation improvements +- development status upgraded to beta (from alpha) - Table of content: - - 1. Documentation - 2. Files - 3. Change Log +### Table of contents +- Release [w11a_V0.60](#user-content-w11a_V0.60) +- Release [w11a_V0.581](#user-content-w11a_V0.581) +- Release [w11a_V0.58](#user-content-w11a_V0.58) +- Release [w11a_V0.57](#user-content-w11a_V0.57) +- Release [w11a_V0.562](#user-content-w11a_V0.562) +- Release [w11a_V0.561](#user-content-w11a_V0.561) +- Release [w11a_V0.56](#user-content-w11a_V0.56) +- Release [w11a_V0.55](#user-content-w11a_V0.55) +- Release [w11a_V0.54](#user-content-w11a_V0.54) +- Release [w11a_V0.532](#user-content-w11a_V0.532) +- Release [w11a_V0.531](#user-content-w11a_V0.531) +- Release [w11a_V0.53](#user-content-w11a_V0.53) +- Release [w11a_V0.52](#user-content-w11a_V0.52) +- Release [w11a_V0.51](#user-content-w11a_V0.51) +- Release [w11a_V0.5](#user-content-w11a_V0.5) -1. Documentation ------------------------------------------------------------- + +--- +## 2014-06-06: w11a_V0.60 - svn rev 25(oc) 559+(wfjm) - More detailed information on installation, build and test can be found - in the doc directory, specifically +### Summary +- many documentation updates; no functional changes - * README.txt: release notes - * INSTALL.txt: installation and building test benches and systems - * w11a_tb_guide.txt: running test benches - * w11a_os_guide.txt: booting operating systems - * w11a_known_issues.txt: known differences, limitations and issues +### New features -2. Files --------------------------------------------------------------------- - - doc Documentation - doc/man man pages for retro11 commands - rtl VHDL sources - rtl/bplib - board and component support libs - rtl/bplib/atlys - for Digilent Atlys board - rtl/bplib/fx2lib - for Cypress FX2 USB interface controller - rtl/bplib/issi - for ISSI parts - rtl/bplib/micron - for Micron parts - rtl/bplib/nexys2 - for Digilent Nexsy2 board - rtl/bplib/nexys3 - for Digilent Nexsy3 board - rtl/bplib/nxcramlib - for CRAM part used in Nexys2/3 - rtl/bplib/s3board - for Digilent S3BOARD - rtl/ibus - ibus devices (UNIBUS peripherals) - rtl/sys_gen - top level designs - rtl/sys_gen/tst_fx2loop - top level designs for Cypress FX2 tester - nexys2,nexys3 - systems for Nexsy2,Nexsy3 - rtl/sys_gen/tst_rlink - top level designs for an rlink tester - nexys2,nexys3,s3board - systems for Nexsy2,Nexsy3,S3BOARD - rtl/sys_gen/tst_rlink_cuff - top level designs for rlink over FX2 tester - nexys2,nexys3,atlys - systems for Atlys,Nexsy2,Nexsy3 - rtl/sys_gen/tst_serloop - top level designs for serport loop tester - nexys2,nexys3,s3board - systems for Nexsy2,Nexsy3,S3BOARD - rtl/sys_gen/tst_snhumanio - top level designs for human I/O tester - atlys,nexys2,nexys3,s3board - systems for Atlys,Nexsy2,Nexsy3,S3BOARD - rtl/sys_gen/w11a - top level designs for w11a SoC - nexys2,nexys3,s3board - w11a systems for Nexsy2,Nexsy3,S3BOARD - rtl/vlib - VHDL component libs - rtl/vlib/comlib - communication - rtl/vlib/genlib - general - rtl/vlib/memlib - memory - rtl/vlib/rbus - rri: rbus - rtl/vlib/rlink - rri: rlink - rtl/vlib/serport - serial port (UART) - rtl/vlib/simlib - simulation helper lib - rtl/vlib/xlib - Xilinx specific components - rtl/w11a - w11a core - tools helper programs - tools/asm-11 - pdp-11 assembler code - tools/asm-11/tests - test bench for asm-11 - tools/asm-11/tests-err - test bench for asm-11 (error check part) - tools/bin - scripts and binaries - tools/dox - Doxygen documentation configuration - tools/make - make includes - tools/fx2 - Firmware for Cypress FX2 USB Interface - tools/fx2/bin - pre-build firmware images in .ihx format - tools/fx2/src - C and asm sources - tools/fx2/sys - udev rules for USB on fpga eval boards - tools/oskit - setup files for Operation System kits - tools/oskit/... - several PDP-11 system kits available - tools/src - C++ sources for rlink backend software - tools/src/librlink - basic rlink interface - tools/src/librlinktpp - C++ to tcl binding for rlink interface - tools/src/librtcltools - support classes to implement Tcl bindings - tools/src/librtools - general support classes and methods - tools/src/librutiltpp - Tcl support commands implemented in C++ - tools/src/librw11 - w11 over rlink interface - tools/src/librwxxtpp - C++ to tcl binding for w11 over rlink iface - tools/tbench - w11 CPU test bench - tools/tcl - Tcl scripts - -3. Change Log ---------------------------------------------------------------- - -- w11a_V0.50 -> w11a_V0.60 cummulative summary of key changes - - revised ibus protocol V2 (in w11a_V0.51) - - revised rbus protocol V3 (in w11a_V0.52) - - backend server rewritten in C++ and Tcl (in w11a_V0.53 and w11a_V0.562) - - add Nexys3 port of w11a (in w11a_V0.54) - - add Cypress FX2 support (in w11a_V0.56 and w11a_V0.57) - - added LP11,PC11 support (in w11a_V0.58) - - reference system now ISE 14.7 and Ubuntu 12.04 64 bit, ghdl 0.31 - - many code cleanups; use numeric_std - - many documentation improvements - - development status upgraded to beta (from alpha) - -- trunk (2014-06-06: svn rev 25(oc) 559+(wfjm); tagged w11a_V0.60) +++++++++ - - - Summary - - many documentation updates; no functional changes - - - New features - Tarballs with ready to use bit files and and all logfiles from the tool chain can be downloaded from + ``` http://www.retro11.de/data/oc_w11/bitkits/ + ``` This area is organized in folders for different releases. The tarball file names contain information about release, Xlinix tool, and design. - - Changes - - documentation updates - - URL of oskits changed, they are now unter - http://www.retro11.de/data/oc_w11/oskits +### Changes +- documentation updates +- URL of oskits changed, they are now unter + http://www.retro11.de/data/oc_w11/oskits/ -- trunk (2014-05-29: svn rev 22(oc) 556(wfjm); untagged w11a_V0.581) ++++++++ + +--- +## 2014-05-29: w11a_V0.581 - svn rev 22(oc) 556(wfjm) - - Summary - - new reference system - - switched from ISE 13.3 to 14.7. - - map/par behaviour changed, unfortunately unfavorably for w11a. - On Nexys3 no timing closure anymore for 80 MHz, only 72 MHz can - be achieved now. - - new man pages (in doc/man/man1/) - - support for Spartan-6 CMTs in PLL and DCM mode +### Summary +- new reference system + - switched from ISE 13.3 to 14.7. + - map/par behaviour changed, unfortunately unfavorably for w11a. + On Nexys3 no timing closure anymore for 80 MHz, only 72 MHz can + be achieved now. +- new man pages (in `doc/man/man1/`) +- support for Spartan-6 CMTs in PLL and DCM mode + +### New features - - New features - new modules - rtl/vlib/xlib - s6_cmt_sfs_unisim - Spartan-6 CMT for simple frequency synthesis @@ -156,22 +106,27 @@ Release notes for w11a - tools/tcl/rw11 - util.tcl - move definitions to defs.tcl - - Bug fixes - - tools/src/librtools/RlogFile - fix date print (month was off by one) - - tools/tcl/rw11/asm.tcl - asmwait checks now pc if stop: defined +### Bug fixes + + - tools/src/librtools/RlogFile - fix date print (month was off by one) + - tools/tcl/rw11/asm.tcl - asmwait checks now pc if stop: defined + +### Other updates - - Other updates - INSTALL_ghdl.txt - text reflects current situation on ghdl packages -- trunk (2013-05-12: svn rev 21(oc) 518+(wfjm); untagged w11a_V0.58) ++++++++ + +--- +## 2013-05-12: w11a_V0.58 - svn rev 21(oc) 518+(wfjm) - - Summary - - C++ and Tcl based backend server now fully functional, supports with - DL11, RK11, LP11 and PC11 all devices available in w11a designs - - the old perl based backend server (pi_rri) is obsolete and removed - - operating system kits reorganized +### Summary +- C++ and Tcl based backend server now fully functional, supports with + DL11, RK11, LP11 and PC11 all devices available in w11a designs +- the old perl based backend server (pi_rri) is obsolete and removed +- operating system kits reorganized + +### New features - - New features - new directory trees for - tools/oskit - operating system kits - new modules @@ -184,26 +139,31 @@ Release notes for w11a - RtclRw11*PC11 - tcl iface for PC11 paper tape handling - RtclRw11*Stream* - tcl iface for Virtual Stream handling - - Changes +### Changes + - renames - - the w11 backend quick starter now named ti_w11 and under tools/bin + - the w11 backend quick starter now named ti_w11 and under `tools/bin` (was rtl/sys_gen/w11a/tb/torri) - all operating system image related material now under - tools/oskit (was under rtl/sys_gen/w11a/tb) + `tools/oskit` (was under rtl/sys_gen/w11a/tb) + +### Bug fixes - - Bug fixes - rtl/ibus/ibdr_lp11 - err flag logic fixed, was cleared in ibus racc read - rtl/ibus/ibdr_pc11 - rbuf logic fixed. Was broken since ibus V2 update in V0.51! Went untested because pc11 rarely used. -- trunk (2013-04-27: svn rev 20(oc) 511(wfjm); untagged w11a_V0.57) +++++++++ + +--- +## 2013-04-27: w11a_V0.57 - svn rev 20(oc) 511(wfjm) - - Summary - - new C++ and Tcl based backend server supports now RK11 handling - - w11a systems operate with rlink over USB on nexsy2 and nexsy3 boards. - See w11a_os_guide.txt for details +### Summary +- new C++ and Tcl based backend server supports now RK11 handling +- w11a systems operate with rlink over USB on nexsy2 and nexsy3 boards. + See w11a_os_guide.txt for details + +### New features - - New features - new modules - rtl/bplib/fx2rlink - new vhdl lib with rlink over fx2 modules - ioleds_sp1c_fx2 - io activity leds for rlink_sp1c_fx2 @@ -217,28 +177,33 @@ Release notes for w11a - new files - rtl/sys_gen/w11a/tb/torri - quick starter for new backend - - Changes +### Changes + - tcl module renames: tools/tcl/rw11a -> tools/tcl/rw11 - - Bug fixes +### Bug fixes + - tools/src/ReventLoop: poll list update logic in DoPoll() corrected -- trunk (2013-04-13: svn rev 19(oc) 505(wfjm); untagged w11a_V0.562) +++++++++ + +--- +## 2013-04-13: w11a_V0.562 - svn rev 19(oc) 505(wfjm) - - Summary - - V0.53 introduced a new C++ and Tcl based backend server, but only the - very basic rlink handling layer. This step release add now many support - classes for interfacing to w11 system designs, and the associated Tcl - bindings. - - add 'asm-11', a simple, Macro-11 syntax subset combatible, assembler. - Can be used stand-alone to generate 'absolute loader' format files, - but also integrates tightly into the Tcl environment and is used as - building block in the creation of CPU test benches. - - use now doxygen 1.8.3.1, generate c++,tcl, and vhdl source docs - See section 9. in INSTALL.txt for details. +### Summary +- V0.53 introduced a new C++ and Tcl based backend server, but only the + very basic rlink handling layer. This step release add now many support + classes for interfacing to w11 system designs, and the associated Tcl + bindings. +- add `asm-11`, a simple, Macro-11 syntax subset combatible, assembler. + Can be used stand-alone to generate 'absolute loader' format files, + but also integrates tightly into the Tcl environment and is used as + building block in the creation of CPU test benches. +- use now doxygen 1.8.3.1, generate c++, tcl, and vhdl source docs + See section 9. in INSTALL.txt for details. + +### New features - - New features - new directory trees for - tools/asm-11 - asm-11 code - tools/asm-11/tests - test bench for asm-11 @@ -254,7 +219,8 @@ Release notes for w11a - *.Doxyfile - new descriptors c++,tcl,vhdl docs - make_dox - driver script to generate c++,tcl,vhdl doxygen docs - - Changes +### Changes + - vhdl module renames: vlib/serport -> vlib/serportlib - vhdl module splits: @@ -262,43 +228,50 @@ Release notes for w11a - C++ class splits librtcltools/RtclProxyBase -> RtclCmdBase + RtclProxyBase -- trunk (2013-01-06: svn rev 18(oc) 472(wfjm); untagged w11a_V0.561) +++++++++ + +--- +## 2013-01-06: w11a_V0.561 - svn rev 18(oc) 472(wfjm) - - Summary - - Added simple simulation model of Cypress FX2 and test benches for - functional verifcation of FX2 controller - - Bugfixes in FX2 firmware and controller, works now also on Nexys3 & Atlys - - Added test systems for rlink over USB verification for Nexys3 & Atlys +### Summary +- Added simple simulation model of Cypress FX2 and test benches for + functional verifcation of FX2 controller +- Bugfixes in FX2 firmware and controller, works now also on Nexys3 & Atlys +- Added test systems for rlink over USB verification for Nexys3 & Atlys + +### New features - - New features - new test benches - rtl/sys_gen/tst_rlink_cuff/nexys2/ic/tb/tb_tst_rlink_cuff_ic_n2 - new systems - rtl/sys_gen/tst_rlink_cuff/nexys2/ic/sys_tst_rlink_cuff_ic_n3 - rtl/sys_gen/tst_rlink_cuff/nexys2/ic/sys_tst_rlink_cuff_ic_atlys - - Bug fixes +### Bug fixes + - tools/fx2/src: FX2 firmware now properly re-initializes hardware registers and will work on Nexys3 and Atlys boards with default Digilent EPROM - rtl/bplib/fx2lib: read pipeline logic in FX2 controller corrected -- trunk (2013-01-02: svn rev 17(oc) 467(wfjm); untagged w11a_V0.56) ++++++++++ + +--- +## 2013-01-02: w11a_V0.56 - svn rev 17(oc) 467(wfjm) - - Summary - - re-organized handling of board and derived clocks in test benches - - added message filter definitions for some designs (.mfset files) - - added Cypress EZ-USB FX2 controller (USB interface) - - added firmware for EZ-USB FX2 supporting jtag access and data transfer - - FPGA configure over USB now supported directly in make build flow - - added test systems for USB testing and rlink over USB verification - - no functional change of w11a CPU core or any pre-existing test systems - - Note: Carefully read the disclaimer about usage of USB VID/PID numbers - in the file README_USB-VID-PID.txt. You'll be responsible for any - misuse of the defaults provided with the project sources !! +### Summary +- re-organized handling of board and derived clocks in test benches +- added message filter definitions for some designs (`.mfset` files) +- added Cypress EZ-USB FX2 controller (USB interface) +- added firmware for EZ-USB FX2 supporting jtag access and data transfer +- FPGA configure over USB now supported directly in make build flow +- added test systems for USB testing and rlink over USB verification +- no functional change of w11a CPU core or any pre-existing test systems +- Note: Carefully read the disclaimer about usage of USB VID/PID numbers + in the file README_USB-VID-PID.txt. You'll be responsible for any + misuse of the defaults provided with the project sources !! - - New reference system - The development and test system was upgraded from Kubuntu 10.04 to 12.04. - The version of several key tools and libraries changed: +### New reference system +The development and test system was upgraded from Kubuntu 10.04 to 12.04. +The version of several key tools and libraries changed: +``` linux kernel 3.2.0 (was 2.6.32) gcc/g++ 4.6.3 (was 4.4.3) boost 1.46.1 (was 1.40) @@ -307,8 +280,9 @@ Release notes for w11a tcl 8.5.11 (was 8.4.19) xilinx ise 13.3 (was 13.1) --> see INSTALL.txt, INSTALL_ghdl.txt and INSTALL_urjtag.txt +``` +### New features - - New features - added firmware for Cypress FX2 controller - tools/fx2 - bin - pre-build firmware images in .ihx file format @@ -325,7 +299,8 @@ Release notes for w11a - tools/bin - xilinx_sdf_ghdl_filter: tool to patch ISE sdf files for usage with ghdl - - Changes +### Changes + - documentation - added a 'system requirements' section in INSTALL.txt - added INSTALL_ghdl.txt and INSTALL_urjtag.txt covering ghdl and urjtag @@ -339,14 +314,17 @@ Release notes for w11a - vlib/rlink/tb/ - tbcore_rlink_dcm - obsolete, use tbcore_rlink -- trunk (2011-12-23: svn rev 16(oc) 442(wfjm); untagged w11a_V0.55) +++++++++ + +--- +## 2011-12-23: w11a_V0.55 - svn rev 16(oc) 442(wfjm) - - Summary - - added xon/xoff (software flow control) support to serport library - - added test systems for serport verification - - use new serport stack in sys_w11a_* and sys_tst_rlink_* systems +### Summary +- added xon/xoff (software flow control) support to serport library +- added test systems for serport verification +- use new serport stack in sys_w11a_* and sys_tst_rlink_* systems + +### New features - - New features - new modules - vlib/serport - serport_xonrx - xon/xoff logic rx path @@ -372,32 +350,39 @@ Release notes for w11a - rlink_serport - obsolete, now all in rlink_sp1c - rlink_base_serport - use now new rlink_sp1c -- trunk (2011-12-04: svn rev 15(oc) 436(wfjm); untagged w11a_V0.54) +++++++++ + +--- +## 2011-12-04: w11a_V0.54 - svn rev 15(oc) 436(wfjm) - - Summary - - added support for nexys3 board for w11a +### Summary +- added support for nexys3 board for w11a + +### New features - - New features - new systems - sys_gen/w11a/nexys3/sys_w11a_n3 - sys_gen/w11a/nexys3/sys_tst_rlink_n3 - - Changes +### Changes + - module renames: bplib/nexys2/n2_cram_dummy -> bplib/nxcramlib/nx_cram_dummy bplib/nexys2/n2_cram_memctl_as -> bplib/nxcramlib/nx_cram_memctl_as - - Bug fixes - - tools/src/lib*: backend libraries compile now on 64 bit systems +### Bug fixes +- tools/src/lib*: backend libraries compile now on 64 bit systems -- trunk (2011-11-20: svn rev 14(oc) 428(wfjm); untagged w11a_V0.532) +++++++++ + +--- +## 2011-11-20: w11a_V0.532 - svn rev 14(oc) 428(wfjm) - - Summary - - generalized the 'human I/O' interface for s3board,nexys2/3 and atlys - - added test design for the 'human I/O' interface - - no functional change of w11a CPU core or any existing test systems +### Summary +- generalized the 'human I/O' interface for s3board,nexys2/3 and atlys +- added test design for the 'human I/O' interface +- no functional change of w11a CPU core or any existing test systems + +### Changes - - Changes - functional changes - use now 'a6' polynomial of Koopman et al for crc8 in rlink - with one exception all vhdl sources use now numeric_std @@ -406,22 +391,26 @@ Release notes for w11a vlib/xlib/dcm_sp_sfs_unisim -> vlib/xlib/dcm_sfs_unisim_s3e vlib/xlib/tb/tb_dcm_sp_sfs -> vlib/xlib/tb/tb_dcm_sfs - - New features +### New features + - new modules - rtl/sys_gen/tst_snhumanio - sub-tree with test design for 'human I/O' interface modules - atlys, nexys2, and s3board directories contain the systems for the respective Digilent boards -- trunk (2011-09-11: svn rev 12(oc) 409(wfjm); untagged w11a_V0.531) +++++++++ + +--- +## 2011-09-11: w11a_V0.531 - svn rev 12(oc) 409(wfjm) - - Summary - - Many small changes to prepare upcoming support for - - Spartan-6 boards (nexys3 and atlys) - - usage of Cypress FX2 USB interface on nexys2/3 and atlys boards - - no functional change of w11a CPU core or any test systems +### Summary +- Many small changes to prepare upcoming support for + - Spartan-6 boards (nexys3 and atlys) + - usage of Cypress FX2 USB interface on nexys2/3 and atlys boards +- no functional change of w11a CPU core or any test systems + +### Changes - - Changes - use boost libraries instead of custom coding: - boost/function and /bind for callbacks, retire RmethDscBase and RmethDsc - boost/foreach for some iterator loops @@ -441,21 +430,24 @@ Release notes for w11a rtl/vlib/xst_vhdl.opt -> rtl/make/syn_s3_speed.opt rtl/vlib/balanced.opt -> rtl/make/imp_s3_speed.opt -- trunk (2011-04-17: svn rev 11(oc) 376(wfjm); untagged w11a_V0.53) ++++++++++ + +--- +## 2011-04-17: w11a_V0.53 - svn rev 11(oc) 376(wfjm) - - Summary - - Introduce C++ and Tcl based backend server. A set of C++ classes provide - the basic rlink communication primitives. Additional glue classes provide - a Tcl binding. This first phase contains the basic functionality needed - to control simple test benches. - - add an 'rlink exerciser' (tst_rlink) and a top level design for a Nexys2 - board (sys_tst_rlink_n2) and a test suite implemented in Tcl. +### Summary +- Introduce C++ and Tcl based backend server. A set of C++ classes provide + the basic rlink communication primitives. Additional glue classes provide + a Tcl binding. This first phase contains the basic functionality needed + to control simple test benches. +- add an rlink exerciser (`tst_rlink`) and a top level design for a Nexys2 + board (`sys_tst_rlink_n2`) and a test suite implemented in Tcl. - - Note: No functional changes in w11a core and I/O system at this point! - The w11a demonstrator systems are still operated with the old - backend code (pi_rri). +- Note: No functional changes in w11a core and I/O system at this point! + The w11a demonstrator systems are still operated with the old + backend code (`pi_rri`). + +### New features - - New features - new directory trees for - C++ sources of backend (plus make and doxygen documentation support) - tools/dox - Doxygen documentation configuration @@ -488,18 +480,22 @@ Release notes for w11a - tools/bin - ti_rri: Tcl driver for rlink tests and servers (will replace pi_rri) -- trunk (2011-01-02: svn rev 9(oc) 352(wfjm); untagged w11a_V0.52) +++++++++++ + +--- +## 2011-01-02: w11a_V0.52 - svn rev 9(oc) 352(wfjm) - - Summary - - Introduce rbus protocol V3 - - reorganize rbus and rlink modules, many renames +### Summary +- Introduce rbus protocol V3 +- reorganize rbus and rlink modules, many renames + +### New features - - New features - vlib/rbus - added several rbus devices useful for debugging - rbd_tester: test target, used for example in test benches - - Changes +### Changes + - module renames: - the rri (remote-register-interface) components were re-organized and cleanly separated into rbus and rlink components: @@ -560,14 +556,17 @@ Release notes for w11a - rlink_serport (re-written) is an adapter to a serial interface - rlink_base_serport (renamed) combines rlink_base and rlink_serport -- trunk (2010-11-28: svn rev 8(oc) 341(wfjm); untagged w11a_V0.51) +++++++++++ + +--- +## 2010-11-28: w11a_V0.51 - svn rev 8(oc) 341(wfjm) - - Summary - - Introduce ibus protocol V2 - - Nexys2 systems use DCM - - sys_w11a_n2 now runs with 58 MHz +### Summary +- Introduce ibus protocol V2 +- Nexys2 systems use DCM +- sys_w11a_n2 now runs with 58 MHz + +### New features - - New features - ibus - added ib_sres_or_mon to check for miss-behaving ibus devices - added ib_sel to encapsulate address select logic @@ -576,7 +575,8 @@ Release notes for w11a - sys_gen/w11a/nexys2 - sys_w11a_n2 now runs with 58 MHz clksys - - Changes +### Changes + - module renames: - in future 'box' is used for large autonomous blocks, therefore use the term unit for purely sequential logic modules: @@ -594,15 +594,17 @@ Release notes for w11a - basic ibus transaction now takes 2 cycles, one for address select, one for data exchange. This avoids too long logic paths in the ibus logic. - - Bug fixes - - rtl/vlib/Makefile.xflow: use default .opt files under rtl/vlib again. +### Bug fixes +- rtl/vlib/Makefile.xflow: use default .opt files under rtl/vlib again. -- w11a_V0.5 (2010-07-23) +++++++++++++++++++++++++++++++++++++++++++++++++++++ + +--- +## 2010-07-23: w11a_V0.5 - Initial release with - - w11a CPU core - - basic set of peripherals: kw11l, dl11, lp11, pc11, rk11/rk05 - - just for fun: iist (not fully implemented and tested yet) - - two complete system configurations with - - for a Digilent S3BOARD rtl/sys_gen/w11a/s3board/sys_w11a_s3 - - for a Digilent Nexys2 rtl/sys_gen/w11a/nexys2/sys_w11a_n2 +### Initial release with +- w11a CPU core +- basic set of peripherals: kw11l, dl11, lp11, pc11, rk11/rk05 +- just for fun: iist (not fully implemented and tested yet) +- two complete system configurations with + - for a Digilent S3BOARD rtl/sys_gen/w11a/s3board/sys_w11a_s3 + - for a Digilent Nexys2 rtl/sys_gen/w11a/nexys2/sys_w11a_n2 diff --git a/doc/CHANGELOG-w11a_V0.60-w11a_V0.70.md b/doc/CHANGELOG-w11a_V0.60-w11a_V0.70.md new file mode 100644 index 00000000..261449bb --- /dev/null +++ b/doc/CHANGELOG-w11a_V0.60-w11a_V0.70.md @@ -0,0 +1,616 @@ +# Changelog: w11a_V0.60 -> w11a_V0.70 + +### Release highlights +- Bugfix for DIV instruction + (in [w11a_V0.61](#user-content-w11a-V0.61), + see [ECO-026-div.md](ECO-026-div.md)) +- revised rbus protocol V4 + (in [w11a_V0.62](#user-content-w11a-V0.63), see README_Rlink_V4.txt) +- add basic Vivado support + (in [w11a_V0.64](#user-content-w11a-V0.64)) +- add Nexys4 and Basys3 port of w11a + (in [w11a_V0.64](#user-content-w11a-V0.64)) +- add RL11/RL02 disk support + (in [w11a_V0.64](#user-content-w11a-V0.64)) +- add RH70+RP/RM disk support + (in [w11a_V0.65](#user-content-w11a-V0.65)) +- add TM11/TY10 tape support + (in [w11a_V0.66](#user-content-w11a-V0.66)) +- reference system now ISE 14.7, Vivado 2014.4; Ubuntu 14.04 64 bit, ghdl 0.31 + +### Table of contents +- Release [w11a_V0.70](#user-content-w11a_V0.70) +- Release [w11a_V0.66](#user-content-w11a_V0.66) +- Release [w11a_V0.65](#user-content-w11a_V0.65) +- Release [w11a_V0.64](#user-content-w11a_V0.64) +- Release [w11a_V0.63](#user-content-w11a_V0.63) +- Release [w11a_V0.62](#user-content-w11a_V0.62) +- Release [w11a_V0.61](#user-content-w11a_V0.61) +- [CHANGELOG for w11a_V.50 to w11a_V0.60.md](CHANGELOG-w11a_V.50-w11a_V0.60.md) + + +--- +## 2015-06-21: w11a_V0.70 - svn rev 33(oc) 693(wfjm) + +### Preface +- resolved known issue V0.66-2: operation with multiple RP or RM disks + under 211bsd works now. Issue was caused by a faulty error check. +- resolved bug tracker issue 2015-06-06: the tm11 offline function works + now as expected. Issue was caused by de-referencing a null pointer. +- resolved bug tracker request 2015-06-05: the values returned as drive + serial number were interpreted by 211bsd standalone code as a signature + of SI drives, which made disk partitioning a bit cumbersome. Changed the + scheme used to generate drive serial numbers such that they never match + these 3rd party drive characteristics. The 211bsd installation on a + RM05 is documented with the `211bsd_tm` oskit. +- the w11a designs grow larger, filling the FPGA's on Nexys2 and Nexys3 + to ~50% (n2) or 67% (n3). To reach timing closure without fine tuning + constraints the cpu clock had to be reduced to + + sys_w11a_n2 now 52 MHz (was 54 MHz) + sys_w11a_n3 now 64 MHz (was 68 MHz) + +- w11a has now a complete set of mass storage peripherals. This is a good + reason of a major release, thus go for version V0.70. +- there are many known issues, and in many cases only core functionality + used by operating systems has been implemented. The missing parts will + be implemented in the upcoming releases towards V0.80, also much more + intensive testing, especially with maindecs (aka xxdp) will be done. + +### Summary +- rhrp and tm11 bug fixes +- no major functionality added + +### Changes + + - renames + - tools/oskit/211bsd_tm/211bsd_tm_boot.* -> 211bsd_tm_rp06_boot.* + - functional changes + - rtl/ibus/ibdr_rhrp - modify sn register to avoid 211bsd issues + - tools/bin/create_disk - support RM80 disks + - tools/tcl/rutil/util.tcl - add dohook + - tools/oskit/*/*_boot.tcl - add preinithook and preboothook + +### Bug fixes + + - rtl/ibus/ibdr_rhrp - set er1.rmr only when unit busy + - set cs2.pge only when controller busy + - tools/src/librw11 + - Rw11CntlTM11 - fix crash when offline function was executed + +### Known issues +- all issues: see README_known_issues.txt +- resolved issues: + - **V0.66-2**: operation with multiple RP/RM drives works now under 211bsd + + +--- +## 2015-06-05: w11a_V0.66 - svn rev 31(oc) 687(wfjm) + +### Preface +- Since the previous release a full set of small, medium and large sized + disks (RK,RL,RP/RM) is available, covering all use cases. Still missing + was a tape system, which allows to install systems from distribution tapes + but is also very handy for data exchange. This release adds a TM11/TU10 + tape controller emulation. This is much simpler to implement than a + massbus based TU16 or TU78 controller. Because storage is emulated there + is neither a speed nor a capacity advantage of 1600 or 6250 bpi drives, + so for all practical purposes the simple 800 bpi TU10 drive emulation is + fully adequate. +- The TM11/TU10 was tested under 211bsd with creating a tape distribution + kit and building a RP06 based system from such a tape. A 211bsd_tm + oskit is provided with a recipe to restore a RP06 from tape. +- bug fixes + - the `ti_rri` event loop aborted under heavy load with three devices, seen + when RP disk, TM tape and DL11 run simultaneously. Was caused by a race + condition in attention handling and dispatching. + - the boot command failed when cpu was running and the unit not decoded + properly, so boots from units other then 0 failed. + +### Summary +- added TM11/TU10 tape support + +### New features + + - new modules + - rtl/ibus/ibdr_rm11 - ibus controller for RM11 + - tools/bin + - file2tap - create a tap container from disk files + - tap2file - split a tap container into disk files + - tools/src/librw11 + - Rw11(Cntl|Unit)TM11 - Controller/Unit for TM11 + - Rw11UnitTape(|Base) - support for tape units + - Rw11VirtTape(|Tap) - virtual tapes (generic and tap containers) + - tools/tcl/rw11 + - tbench.tcl - support sub directories and return in tests + - new oskits + - tools/oskit/211bsd_tm - 2.11BSD tape distribution kit (for RP06) + +### Changes + + - renames + - tools/tbench - the text benches were re-organized and + grouped now in sub directories: + cp for w11a control port + w11a for w11a CPU tests + rhrp for RHRP device tests + tm11 for TM11 device tests + - functional changes + - tools/bin/create_disk - add RM80 support + +### Bug fixes + + - tools/src/librlink + - RlinkServer - fix race condition in attention handling + - tools/src/librw11 + - Rw11Cpu - stop cpu before load, proper unit handling + +### Known issues +- all issues: see README_known_issues.txt +- resolved issues: _none_ +- new issues: + - **V0.66-1**: the TM11 controller transfers data byte wise (all disk do it + 16bit word wise) and allows for odd byte length transfers. Odd length + transfers are currently not supported and rejected as invalid command. + Odd byte length records aren't used by OS, if at all, so in practice + this limitation isn't relevant. + - **V0.66-2**: using two RP06 drives in parallel under 211bsd leads to a + hangup of the system after a short time. Currently only operation + of a single drive works reliably. + + +--- +## 2015-05-14: w11a_V0.65 - svn rev 30(oc) 681(wfjm) + +### Preface +- With small RK05 or RL02 sized disks only quite reduced OS setups could + be booted, full featured systems were beyond reach. Now finally large + disks are available, with a RH70 + RP/RM disk controller emulation. It + supports up to four disks and allows now to run full featured 211bsd + or rsx-11mplus systems. +- to track down issues with ibus devices a 'ibus monitor' was added, it can + record in the default setup up to 511 ibus transactions. An address filter + allows to select accesses of one device. The `ibd_ibmon tcl` package + contains the appropriate support scripts. +- several cleanups + - factor out common blocks on sys_w11a_* systems: the core+rbus+cache + logic of single cpu systems now contained in `pdp11_sys70`, and the + human I/O for digilent boards now in `pdp11_hio70`. + - cpu start/stop logic cleanup: new command set with simple commands. + Add also a new suspend/resume mechanism, which allows to hold the cpu + without leaving the 'run state'. While suspended all timers are frozen. + Very helpful when debugging, will be the basis for a hardware break + point logic in a later release. + - xon/xoff consolidation: escaping now done in `cdata2byte`/`byte2cdata` in + FPGA and in `RlinkPacketBufSnd`/`RlinkPacketBufRcv` in backend. The extra + escaping level in `serport_xonrx`/`serport_xontx` isn't used anymore, the + special code in `RlinkPortTerm` has been removed. This allows to use + `xon/xoff` flow control also in simulation links via `RlinkPortFifo`. + - status check cleanup: it is very helpful to have a default status check + and an easy way to modify it cases where some error flags are expected + (e.g. on device polls). In the old logic status and data checks were + done via `RlinkCommandExpect`. The new logic reflects that status checks + are the normal case, and store the status check pattern in `RlinkCommand`. + The meaning of expect masks for status and data is inverted, now a '1' + means that the bit is checked (before it meant the bit is ignored). + The default status check pattern is still in `RlinkContext`, but will be + copied to `RlinkCommand` when the list is processed. `RlinkCommandExpect` + handles now only data checks. + +- and bug fixes + - rk11 cleanup: since the first days 211bsd autoconfig printed + + rk ? csr 177400 vector 220 didn't interrupt + + for boots from a RK11 it didn't have consequences, but when booted from + a RL,RP, or RM disk this prevents that the RK11 disks are configured. + Was caused by a missing interrupt after device reset. Now fixed. + +### Summary +- added RH70/RP/RM big disk support +- many cleanups + +### New features + + - new directory trees for + - tools/asm-11/lib - definitions and macros for asm-11 + - new modules + - rtl/vlib/serport + - serport_master - serial port module, master side + - rtl/ibus/ibd_ibmon - ibus monitor + - rtl/ibus/ibdr_rhrp - ibus controller for RH70 plus RP/RM drives + - rtl/w11a/pdp11_sys70 - 11/70 system - single core +rbus,debug,cache + - rtl/w11a/pdp11_hio70 - hio led and dsp for sys70 + - tools/src/librw11 + - Rw11(Cntl|Unit)RHRP - Controller/Unit for RHRP + - tools/tbench + - test_rhrp_* - test tbench for RHRP + - new oskits + - tools/oskit/211bsd_rp - new oskit for 2.11BSD on RP06 + - tools/oskit/rsx11mp-30_rp - new oskit for RSX-11Mplus V3.0 on RP06 + +### Changes + + - renames + - rtl/w11a/pdp11_sys70 -> pdp11_reg70 (_sys70 now different function) + - functional changes + - rtl/bplib/*/tb/tb_* - use serport_master instead of + serport_uart_rxtx, allow xon/xoff + - rtl/bplib/fx2rlink + - rlink_sp1c_fx2 - add rbd_rbmon (optional via generics) + - rtl/vlib/rlink/rlink_sp1c - add rbd_rbmon (optional via generics) + - rtl/ibus/ibd_kw11l - freeze timer when cpu suspended + - tools/bin/tbrun_tbwrri - add --fusp,--xon + - tools/bin/ti_w11 - rename -fu->-fc, add -f2,-fx; setup defaults + - tools/bin/librlink + - RlinkCommandList - add SetLastExpect() methods + - RlinkPort - add XonEnable() + - RlinkPortCuff - add noinit attribute + - RlinkPort(Fifo|Term) - add xon,noinit attributes + - tools/src/librw11 + - Rw11Cpu - add AddRbibr(), AddWbibr(), RAddrMap() + - tools/bin/librlinktpp + - RtclRlinkConnect - errcnt: add -increment + log: add -bare,-info.. + wtlam: allow tout=0 for attn cleanup + init: new command + exec: drop -estatdef + - RtclRlinkServer - get/set interface added + - tools/src/librwxxtpp + - RtclRw11Cntl - start: new command + - RtclRw11Cpu - cp: add -rbibr, wbibr, -rreg,...,-init + - cp: add -estat(err|nak|tout), drop estatdef + - rename amap->imap; add rmap + +### Bug fixes + + - rtl/ibus + - ibdr_rk11 - interrupt after dreset and seek command start + - tools/src/librlink + - RlinkConnect - WaitAttn(): return 0. (not -1.) if poll + - RlinkServer - Stop(): fix race in (could hang) + +### Known issues +- all issues: see README_known_issues.txt +- resolved issues: _none_ +- new issues: + - **V0.65-1**: ti_rri sometimes crashes in normal rundown (exit or ^D) when + a cuff: type rlink is active. One gets + + terminate called after throwing an instance of 'Retro::Rexception' + what(): RlinkPortCuff::Cleanup(): driver thread failed to stop + + doesn't affect normal operation, will be fixed in upcoming release. + - **V0.65-2**: some exotic RH70/RP/RM features and conditions not implemented + - last block transfered flag (in DS) + - `CS2.BAI` currently ignored and not handled + - read or write 'with header' gives currently ILF + All this isn't used by any OS, so in practice not relevant. + + +--- +## 2015-03-01: w11a_V0.64 - svn rev 29(oc) 655(wfjm) + +### Preface +- The w11 project started on a Spartan-3 based Digilent S3board, and soon + moved on to a Nexys2 with much better connectivity. Next step was the + Spartan-6 based Nexys3. Now is time to continue with 7-Series FPGAs. +- When Vivado started in 2013 it was immediately clear that the architecture + is far superior to ISE. But tests with the first versions were sobering, + the w11a design either didn't compile at all, or produced faulty synthesis + results. In 2014 Vivado matured, and the current version 2014.4 works + fine with the w11a code base. +- The original Nexys4 board allowed to quickly port Nexys3 version because + both have the same memory chip. The newer Nexys4 DDR will be addressed + later. +- The BRAM capacity of FPGAs increased significantly over time. The low + cost Basys3 board with the second smallest Artix-7 (XC7A35T) has 200 KB + BRAM. That allows to implement a purely BRAM based w11a system with + 176 kB memory. Not enough for 2.11BSD, but for many other less demanding + OS available for a PDP11. +- The Nexyx4 and Basys3 have 16 LEDs. Not quite the 'blinking lights' + console of the classic 11/45 and 11/70, but enough to display the + well known OS typical light patterns the veterans remember so well. +- With a new design tool, a new FPGA generation, two new boards, and a + new interface for the rlink connection that some of the code and tools + base had to be re-organized. +- Last but not least: finally access to a bit bigger disks: RL11 support +- Many changes, some known issues, some rough edges may still lurke around + +### Summary +- added support for Vivado +- added support for Nexys4 and Basys3 boards +- added RL11 disk support +- lots of documentation updated + +### New features + + - new directory trees for + - rtl/bplib/basys3 - support for Digilent Basys3 board + - rtl/bplib/nexys4 - support for Digilent Nexys4 board + - rtl/make_viv - make includes for Vivado + - new files + - tools/bin/xviv_ghdl_unisim - ghdl compile Vivado UNISIM & UNIMACRO libs + - new modules + - rtl/ibus/ibdr_rl11 - ibus controller for RL11 + - rtl/vlib/rlink/ioleds_sp1c - io activity leds for rlink+serport_1clk + - rtl/vlib/xlib + - s7_cmt_sfs_gsim - Series-7 CMT: simple vhdl model + - s7_cmt_sfs_unisim - Series-7 CMT: wrapper for UNISIM + - rtl/w11a + - pdp11_bram_memctl - simple BRAM based memctl + - pdp11_dspmux - mux for hio display + - pdp11_ledmux - mux for hio leds + - pdp11_statleds - status led generator + - tools/src/librw11/ + - Rw11*RL11 - classes for RL11 disk handling + - tools/src/librwxxtpp + - RtclRw11*RL11 - tcl iface for RL11 disk handling + - new systems + - rtl/sys_gen/tst_rlink - rlink tester + - basys3/sys_tst_rlink_b3 - for Basys3 + - nexys4/sys_tst_rlink_n4 - for Nexys4 + - rtl/sys_gen/tst_serloop - serport loop tester + - nexys4/sys_tst_serloop_n4 - for Nexys4 + - rtl/sys_gen/tst_snhumanio - human I/O tester + - basys3/sys_tst_snhumanio_b3 - for Basys3 + - nexys4/sys_tst_snhumanio_n4 - for Nexys4 + - rtl/sys_gen/w11a - w11a + - basys3/sys_w11a_b3 - small BRAM only (176 kB memory) + - nexys4/sys_w11a_n4 - with full 4 MB memory using cram + - new oskits + - tools/oskit/211bsd_rl - new oskit for 2.11BSD on RL02 + - tools/oskit/rt11-53_rl - new oskit for RT11 V5.3 on RL02 + - tools/oskit/xxdp_rl - new oskit for XXDP 22 and 25 on RL02 + +### Changes + + - renames + - ensure that old ISE and new Vivado co-exists, ensure telling names + - rtl/make -> make_ise + - rtl/bplib/bpgen/sn_4x7segctl -> sn_7segctl + - tools/bin/isemsg_filter -> xise_msg_filter + - tools/bin/xilinx_ghdl_unisim -> xise_ghdl_unisim + - tools/bin/xilinx_ghdl_simprim -> xise_ghdl_simprim + + - retired files + - rtl/bplib/fx2lib + - fx2_2fifoctl_as - obsolete, wasn't actively used since long + - tools/bin + - set_ftdi_lat - obsolete, since kernel 2.6.32 the default is 1 ms + - xilinx_vhdl_chop - obsolete, since ISE 11 sources come chopped + + - functional changes + - $RETROBASE/Makefile - re-structured, many new targets + - rtl/bplib/bpgen + - sn_7segctl - handle also 8 digit displays + - sn_humanio - configurable SWI and DSP width + - sn_humanio_rbus - configurable SWI and DSP width + - rtl/vlib/serport + - serport_1clock - export fractional part of divider + - rtl/ibus + - ibdr_maxisys - add RL11 (ibdr_rl11) + - rtl/sys_gen/w11a/* + - sys_w11a_* - use new led and dsp control modules + - tools/src/librlink + - RlinkConnect - drop LogOpts, indivitual getter/setter + - RlinkPortTerm - support custom baud rates (5M,6M,10M,12M) + - tools/src/librtcltools + - RtclGetList - add '?' (key list) and '*' (kv list) + - RtclSetList - add '?' (key list) + - RlogFile - Open(): now with cout/cerr support + - tools/src/librlinktpp + - RtclRlinkConnect - drop config cmd, use get/set cmd + - RtclRlinkPort - drop config cmd, use get/set cmd + - tools/src/librw11 + - Rw11Rdma - PreExecCB() with nwdone and nwnext + - Rw11UnitDisk - add Nwrd2Nblk() + - tools/src/librwxxtpp + - RtclRw11CntlFactory - add RL11 support + - tools/bin + - xise_ghdl_unisim - handle also UNIMACRO lib + - vbomconv - handle Vivado flows too + +### Bug fixes + + - tools/src/librw11 + - Rw11CntlRK11 - revise RdmaPostExecCB() logic + +### Known issues +- resolved issues: _none_ +- new issues: + - **V0.64-7**: ghdl simulated OS boots via ti_w11 (-n4 ect options) fail due to + a flow control issue (likely since V0.63). + - **V0.64-6**: IO delays still unconstraint in vivado. All critical IOs use + explicitly IOB flops, thus timing well defined. + - **V0.64-5**: w11a_tb_guide.txt covers only ISE based tests + (see also V0.64-4). + - **V0.64-4**: No support for the Vivado simulator (xsim) yet. With ghdl only + functional simulations, post synthesis (_ssim) fails to compile. + - **V0.64-3**: Highest baud rate with basys3 and nexys4 is 10 MBaud. 10 MBaud + is not supported according to FTDI, but works. 12 MBaud in next release. + - **V0.64-2**: rlink throughput on basys3/nexys4 limited by serial port stack + round trip times. Will be overcome by libusb based custom driver. + - **V0.64-1**: The large default transfer size for disk accesses leads to + bad throughput in the DL11 emulation for low speed links, like the + 460kBaud the S3board is limited to. Will be overcome by a DL11 + controller with more buffering. + + +--- +## 2015-01-04: w11a_V0.63 - svn rev 28(oc) 629(wfjm) + +### Summary +- the w11a rbus interface used so far a narrow dynamically adjusted + rbus->ibus window. Replaces with a 4k word window for whole IO page. +- utilize rlink protocol version 4 features in w11a backend + - use attn notifies to dispatch attn handlers + - use larger blocks (7*512 rather 1*512 bytes) for rdma transfers + - use labo and merge csr updates with last block transfer + - this combined reduces the number of round trips by a factor 2 to 3, + and in some cases the throughput accordingly. + +### Remarks on reference system +- still using tcl 8.5 (even though 8.6 is now default in Ubuntu 14.04) +- don't use doxygen 1.8.8 and 1.8.9, it fails to generate vhdl docs + +### New features + + - new modules + - tools/bin + - ghdl_assert_filter - filter to suppress startup warnings + - tbrun_tbw - wrapper for tbw based test benches + - tbrun_tbwrri - wrapper for ti_rri + tbw based test benches + - tools/src/librw11 + - Rw11Rdma - Rdma engine base class + - Rw11RdmaDisk - Rdma engine for disk emulation + +### Changes + + - rtl/vlib/rlink + - rlink_core - use 4th stat bit to signal rbus timeout + - rtl/vlib/rbus + - rbd_rbmon - reorganized, supports now 16 bit addresses + - rtl/w11a + - pdp11_core_rbus - use full size 4k word ibus window + - tools/bin/tbw - add -fifo and -verbose options + - tools/src/librtools + - Rexception - add ctor from RerrMsg + - tools/src/librlink + - RlinkCommandExpect - rblk/wblk done counts now expectable + - RlinkConnect - cleanups and minor enhancements + - RlinkServer - use attn notifies to dispatch handlers + - tools/src/librw11 + - Rw11CntlRK11 - re-organize, use now Rw11RdmaDisk + - Rw11Cpu - add ibus address map + - tools/src/librwxxtpp + - RtclRw11CntlRK11 - add get/set for ChunkSize + - RtclRw11Cpu - add amap sub-command for ibus map access + +### Known issues +- resolved issues: + - **V0.62-3**: the rbus monitor (rbd_rbmon) has been updated to handle + 16 bit addresses + + +--- +## 2014-12-20: w11a_V0.62 - svn rev 27(oc) 614(wfjm) + +### Summary +- migrate to rlink protocol version 4 + - Goals for rlink v4 + - 16 bit addresses (instead of 8 bit) + - more robust encoding, support for error recovery at transport level + - add features to reduce round trips + - improved attention handling + - new 'list abort' command + - For further details see README_Rlink_V4.txt +- use own C++ based tcl shell tclshcpp instead of tclsh +- Notes: + 1. rlink protocol, core, and backend are updated in this release + 2. error recovery in backend not yet implemented + 3. the designs using rlink are still essentially unchanged + 4. the new rlink v4 features will be exploited in upcoming releases + +### New reference system +The development and test system was upgraded from Kubuntu 12.04 to 14.04. +The version of several key tools and libraries changed: + + linux kernel 3.13.0 (was 3.2.0) + gcc/g++ 4.8.2 (was 4.6.3) + boost 1.54 (was 1.46.1) + libusb 1.0.17 (was 1.0.9) + perl 5.18.2 (was 5.14.2) + tcl 8.5.15 (was 8.5.11) + sdcc 3.3.0 (was 2.9.0) + doxygen 1.8.7 {installed from sources; Ub 14.04 has 1.8.6} + +Notes: + 1. still using tcl 8.5 (even though 8.6 is now default in Ub 14.04) + 2. sdcc 3.x is not source compatible with sdcc 2.9. The Makefile + allows to use both, see tools/fx2/src/README.txt . + 3. don't use doxygen 1.8.8, it fails to generate vhdl docs + +### New features + + - new environment variables `TCLLIB` and `TCLLIBNAME`. `TCLLIBNAME` must be + defined, and hold the library name matching the Tcl version already + specified with `TCLINC`. + - new modules + - rtl/vlib/comlib/crc16 - 16 bit crc generator (replaces crc8) + - tools/src/tclshcpp/* - new tclshcpp shell + +### Changes + + - rtl/vlib/comlib + - byte2cdata,cdata2byte - re-write, commas now 2 byte sequences + - rtl/vlib/rlink + - rlink_core - re-write for rlink v4 + - rtl/*/* - use new rlink v4 iface and 4 bit STAT + - rtl/vlib/rbus/rbd* - new addresses in 16 bit rlink space + - rtl/vlib/simlib/simlib - add simfifo_*, wait_*, writetrace + - tools/bin/ + - fx2load_wrapper - use _ic instead of _as as default firmware + - ti_rri - use tclshcpp (C++ based) rather tclsh + - tools/fx2/bin/*.ihx - recompiled with sdcc 3.3.0 + bugfixes + - tools/fx2/src/Makefile - support sdcc 3.3.0 + - tools/src/ + - */*.cpp - adopt for rlink v4; use nullptr + - librlink/RlinkCrc16 - 16 crc, replaces RlinkCrc8 + - librlink/RlinkConnect - many changes for rlink v4 + - librlink/RlinkPacketBuf* - re-write for for rlink v4 + - tools/tcl/*/*.tcl - adopt for rlink v4 + - renames: + - tools/bin/telnet_starter -> tools/bin/console_starter + +### Bug fixes + + - tools/fx2/src + - dscr_gen.A51 - correct string 0 descriptor + - lib/syncdelay.h - handle triple nop now properly + +### Known issues +- new issues: + - **V0.62-1**: rlink v4 error recovery not yet implemented, will crash on error + - **V0.62-2**:command lists aren't split to fit in retransmit buffer size + _{both issues are not relevant for w11 backend over USB usage because the + backend produces proper command lists and the USB channel is error free}_ + - **V0.62-3**:the rbus monitor (`rbd_rbmon`) not yet handling 16 bit addresses + and therefore of limited use + + +--- +## 2014-08-08: w11a_V0.61 - svn rev 25(oc) 579(wfjm) +### Summary +- The `div` instruction gave wrong results in some corner cases when either + divisor or quotient were the largest negative integer (100000 or -32768). + This is corrected now, for details see [ECO-026-div.md](ECO-026-div.md) +- some minor updates and fixes to support scripts +- `xtwi` usage and `XTWI_PATH` setup explained in INSTALL.txt + +### New features +- the Makefile's for in all rtl building block directories allow now to + configure the target board for a test synthesis via the `XTW_BOARD` + environment variable or `XTW_BOARD=` make option. + +### Changes + + - tools/bin/asm-11 - add call and return opcodes + - tools/bin/create_disk - add RM02,RM05,RP04,RP07 support + - tools/bin/tbw - use xtwi to start ISim models + - tools/bin/ticonv_pdpcp - add --tout and --cmax; support .sdef + - tools/dox/*.Doxyfile - use now doxygen 1.8.7 + - tools/src/librw11 + - Rw11CntlRK11 - add statistics + +### Bug fixes + + - rtl/w11a - div bug ECO-026 + - pdp11_munit - port changes; fix divide logic + - pdp11_sequencer - s_opg_div_sr: check for late div_quit + - pdp11_dpath - port changes for pdp11_munit + - tools/bin/create_disk - repair --boot option (was inaccessible) + - tools/bin/ti_w11 - split args now into ti_w11 opts and cmds + - tools/src/librwxxtpp + - RtclRw11Cpu - redo estatdef logic; avoid LastExpect() + - tools/dox/make_doxy - create directories, fix 'to view use' text diff --git a/doc/CHANGELOG-w11a_V0.70-w11a_V0.74.md b/doc/CHANGELOG-w11a_V0.70-w11a_V0.74.md new file mode 100644 index 00000000..af922a99 --- /dev/null +++ b/doc/CHANGELOG-w11a_V0.70-w11a_V0.74.md @@ -0,0 +1,603 @@ +# Changelog: w11a_V0.70 -> w11a_V0.74 + +### Table of contents +- Release [w11a_V0.74](#user-content-w11a_V0.74) +- Release [w11a_V0.73](#user-content-w11a_V0.73) +- Release [w11a_V0.72](#user-content-w11a_V0.72) +- Release [w11a_V0.71](#user-content-w11a_V0.71) +- [CHANGELOG for w11a_V.60 to w11a_V0.70.md](CHANGELOG-w11a_V.60-w11a_V0.70.md) +- [CHANGELOG for w11a_V.50 to w11a_V0.60.md](CHANGELOG-w11a_V.50-w11a_V0.60.md) + + +--- +## 2016-10-02: w11a_V0.74 - svn rev 37(oc) 811(wfjm) +### Preface +- the current version of the memory controller for the micron `mt45w8mw16b` + 'cellular ram' used on nexys2, nexys3, and nexys4 uses the asynchronous + access mode. The device supports a 'page mode' to speed up read access to + subsequent addresses. Even though prepared in the controller logic this + feature was simply forgotten. This is now properly implemented and + results in a bit faster cache line load times. The overall performance + of a w11a design is measurably, but marginally better. +- many unit tests still used a ISE environment. All board independent + tests were converted now to a vivado environment, only tests which + really depend a FPGA not supported by vivado stay with ISE. +- a total of 82 unit or system tests are currently available. Many of them + can be executed by different simulation engines, ghdl or the ISE/vivado + build-in simulators, and for different stages of the implementation flow, + from initial behavioral simulation over post-synthesis functional to final + post-routing timing simulation. This results in a large number of possible + tests. All test benches are all self-checking, but the execution of them + was so far not sufficiently automatized. + This was addressed with `tbrun`, a test bench driver, which obtains a + list of all available test benches from configuration files, selects + a subset given by selection criteria, and executes them. It can handle + the parallel execution of tests so multi-core systems can be very + easily exploited. Running all tests is now a single shell command. +- a new tool 'tbfilt' simplifies the logic of self-checking test benches + and can also be used as a tool to analyze the full log files produced + by the test benches +- several test benches have been added to this release, most notably the + memory tester sys_tst_sram_* which was originally developed to verify + the s3board SRAM controller and later ported to verify the nexys* CRAM + controller. +- the system test benches with SRAM and CRAM now include the PCB trace + delay between FPGA and memory chip. The new entity `simbididly` models a + bi-directional bus delay. +- so far test benches ended by stopping the clock, all processes were + written such that they enter a permanent wait, which causes the simulation + to stop. Worked for fine behavioral simulations, but fails when Xilinx + MMCMs are involved in post-synthesis simulations. The UNISIM models + apparently have timed waits. The test benches were modified to stop via a + report with severity failure, the test environment detects this specific + assertion/report failure and accepts it as successful termination of + the simulation. +- the configuration of the board switches in system test benches was done + in a sub-optimal way which could lead to startup problems. tbrun_tbwrri + uses now a different mechanism which ensures that all board and test + bench configuration is done in the first ns of the simulation and has + thus completed well before all other activities. +- finally a caveat: post-synthesis simulations work fine with ISE, but + currently not with vivado, even in case of almost identical designs, + like `sys_tst_rlink_n3` vs `sys_tst_rlink_n4`. Is under investigation. + +### Summary +- upgraded CRAM controller, now with 'page mode' support +- new test bench driver tbrun, give automatized test bench execution + +### New features + + - new modules + - rtl/bplib/issi/tb/* - added unit test for is61lv25616al model + - rtl/bplib/micron/tb/* - added unit test for mt45w8mw16b model + - rtl/sys_gen/tst_serloop - add serloop2 (2 clock) designs for n3,n4 + - nexys3/sys_tst_serloop2_n3.vhd + - nexys4/sys_tst_serloop2_n4.vhd + - rtl/sys_gen/tst_sram - add sram test design for + - nexys2/* + - nexys3/* + - nexys4/* + - s3board/* + - rtl/vlib/genlib/tb + - clkdivce_tb.vhd - copy for tb usage of clkdivce + - rtl/vlib/rlink/tb + - rlink_tba.vhd - rlink test bench adapter + - tb_rlink_tba.vhd - test bench for rbus devices + - tbd_tba_ttcombo.vhd - tba tester for ttcombo + - rtl/vlib/simlib + - simbididly.vhd - bi-di bus delay model + - rtl/vlib/xlib + - gsr_pulse.vhd - pulse GSR at startup + - gsr_pulse_dummy.vhd - no-action dummy (for bsim models) + - rtl/w11a/tb + - tb_rlink_tba_pdp11core.vhd - tba tester for w11a + + - new files + - doc/man/man1 - added tbrun,tbfilt man pages + - */tbrun.yml - test bench descriptors for tbrun + - rtl/sys_gen/w11a/tb + - tb_w11a_mem70*.dat - stim files for additional tests + - rtl/w11a/tb + - tb_pdp11core_ubmap.dat - stim files for additional test + - tools/bin + - njobihtm - determine #jobs + - tbfilt - test bench output filter + - tbrun - test bench driver + - ticonv_rri - converts old 'mode rri' for ti_rri + - tools/tcl/tst_sram/*.tcl - support for sys_tst_sram + +### Changes + + - rtl/bplib + - arty/tb/tb_arty.vhd - add gsr_pulse (provisional....) + - */tb/tb_*.vhd - tbcore_rlink without CLK_STOP now + - fx2lib/tb/fx2_2fifo_core.vhd - proc_ifclk: remove clock stop + - nexys2/tb/tb_nexys2_core.vhd - use simbididly + - nexys3/tb/tb_nexys3_core.vhd - use simbididly + - nexys4/tb/tb_nexys4_cram.vhd - use simbididly + - nxcramlib + - nx_cram_memctl_as.vhd - add page mode support + - nxcramlib.vhd - add cram_*delay functions + - s3board + - s3_sram_memctl.vhd - drop "KEEP" for data (better for dbg) + - tb/tb_s3board_core.vhd - use simbididly + - rtl/make_ise + - generic_ghdl.mk - ghdl_clean: remove also gcov files + - rtl/make_viv + - generic_ghdl.mk - ghdl_clean: remove also gcov files + - generic_vivado.mk - viv_clean: rm only vivado logs + - generic_xsim.mk - xsim work dir now xsim.. + - rtl/sys_gen/tst_serloop + - */tb/tb_tst_serloop*.vhd - remove CLK_STOP logic + - tb/tb_tst_serloop.vhd - remove CLK_STOP logic + - rtl/sys_gen/w11a/nexys* + - sys_conf.vhd - use cram_*delay functions + - rtl/vlib/rlink + - rlink_core.vhd - remove 'assert false' from report stmts + - tb/tb_rlink.vhd - use clkdivce_tb + - tbcore/tbcore_rlink.vhd - conf: add .wait, CONF_DONE; drop CLK_STOP + - rtl/vlib/simlib + - simbus.vhd - rename SB_CLKSTOP > SB_SIMSTOP + - simclk.vhd - CLK_STOP now optional port + - rtl/vlib/xlib + - */s*_cmt_sfs_*.vhd - remove 'assert false' from report stmts + - tools/bin + - tbrun_tbwrri - add --r(l|b)mon,(b|s)wait; configure + now via _conf={...} + - tbw - use {} as delimiter for immediate mode + - vbomconv - add VBOMCONV_GHDL_OPTS and .._GHDL_GCOV + - xise_ghdl_* - add ghdlopts as 1st option; def is -O2 + + - removed files + - tools/bin/ghdl_assert_filter - obsolete (use tbfilt now) + - renames + - rtl/make_viv/viv_*.tcl -> tools/vivado - separate make and tools + +### Bug fixes + + - tools/bin + - tbw - xsim: append -R to ARGV (was prepended...) + - xtwi - add ":." to PATH even under BARE_PATH + +### Known issues +- all issues: see README_known_issues.txt +- no resolved or new issues in this release + + +--- +## 2016-06-26: w11a_V0.73 - svn rev 36(oc) 779(wfjm) +### Preface +- the 'basic vivado support' added with V0.64 was a minimal effort port of + the code base used under ISE, leading to sub-optimal results under vivado. + - the FSM inference under vivado is quirky and has several issues. The + most essential one prevented re-coding with 'one_hot' encoding, which + lead to high logic depth and low clock rates. Proper work-arounds were + applied to almost all FSMs, now vivado infers all (but one) properly + and re-codes them as 'one_hot'. That is especially important for the + pdp11_sequencer, which has 113 states. The sys_w11a_n4 system can now + run with up to 90 MHz (was 75-80 MHz before). + - due to a remaining synthesis issue the dmscnt and dmcmon debug units + are currently disabled for Artix based systems (see issue V0.73-3). + - memory inference is now used for all distributed and block rams under + vivado. The memory generators in memlib are still used under ISE + Note: they were initially setup to work around ISE synthesis issues. + - vivado synthesis and implementation use now 'explore' type flows for + optimal timing performance. + - the two clock dram based fifo was re-written (as `fifo_2c_dram2`) to allow + proper usage of vivado constraints (e.g. scoped xdc). +- vivado is now the prime platform for all further development + - the component test benches run now by default under Vivado with an + Artix-7 as default target. The makefiles for ISE with a Spartan-6 target + are available as `Makefile.ise` and via the `makeise` command. + - a message filter (`xviv_msg_filter`) has been developed which lists only + the unexpected message of a synthesis or implementation run. Filter + rule sets (`.vmfset` files) are available for all designs. + - full support for the vivado simuator `xsim` has been added, there are + make targets to build a behavioral simulation as well as post-synthesis, + post-optimize, and post-routing functional and timing models. All these + models are now created in separate sub-directories and can now co-exist. + However see issues V0.73-1 and V0.73-2 for severe caveats on xsim. + - vivado write_vhdl generates code which violates a vhdl language rule. + Attributes of port signals are declared in the wrong place. xsim and + other simulators accept this, but ghdl doesn't. As a work-around the + generated code is cleaned up by a filter (see xviv_sim_vhdl_cleanup). +- additional rlink devices + - the XADC block, available on all 7Series FPGAs, is now accessible via + rlink on all Arty, Basys3 and Nexys4 designs. Especially useful on the + Arty board because on this board also the currents are monitored. + - the USR_ACCESS register, available on all 7Series FPGAs, is now readable + via rlink on all Arty, Basys3 and Nexys4 designs. The vivado build flow + initializes this register with the build timestamp. This allows to + verify the build time of a design at run time. +- the cache used by the w11a (`pdp11_cache`) was initialy developed with the + tight block ram resources of the early Spartan-3 systems in mind. It had + 8 kByte and used 5 BRAMs of size 18 kBit. With very little changes the + implenenation is now parametrized, and can generate also 16,32, 64 and + even 128 kByte caches which also use the 36 kBit BRAMs on the Artix. + There is a trade-off between cache sizes and clock rate due to routing + delays to the BRAM blocks. The w11a on the nexys4 runs with 16 kByte + cache and 90 MHz clock or with 64 kByte cache and 80 MHz. For practical + work loads, like a kernel compile, the 64 kByte configuration is better + and thus the default. +- resolved known issue V0.64-7: was caused by a combination of issues + and is now resolved by a combination of measures: add portsel logic for + arty tb, proper portsel setup, configurable timeout, and finally proper + timeout setting. +- resolved known issue V0.64-3: So far the arty, basys3 and nexys4 serial + port, based on a FTDI FT2232, was often operated at 10 MBaud. This rate + is in fact not supported by FTDI, the chip will use 8 instead of 10 MBaud. + Due to auto-bauding, which simly adapts to the actual baud rate, this went + undetected for some time. Now all designs use a serport block clocked with + 120 MHz and can be operated with 12 MBaud. + +### Summary +- new reference system: switched to Vivado 2016.2 (from 2015.4) +- code base cleaned-up for vivado, fsm now inferred +- xsim support complete (but many issues to be resolved yet) +- added configurable w11a cache +- removed some never documented and now strategically obsolete designs: + - sys_tst_fx2loop (for nexys2 and nexys3) + - sys_tst_rlink_cuff_ic3 (a three channel variant of the fx2 interface) + +### New features + + - new modules + - rtl/vlib + - generic_clk_100mhz.xdc - generic 100 MHz on CLK constraint (for tbs) + - rtl/vlib/cdclib - new directory for clock domain crossing + - cdc_pulse.vhd - cdc for a pulse (moved in from genlib) + - cdc_signal_s1.vhd - cdc for a signal, 2 stage + - cdc_vector_s0.vhd - cdc for a vector, 1 stage + - rtl/vlib/memlib + - fifo_2c_dram2.vhd - re-write of fifo_2c_dram to allow + proper usage of vivado constraints + - rtl/vlib/rbus + - rb_sres_or_6.vhd - rbus result or, 6 input + - rbd_usracc.vhd - return usr_access register + - rtl/vlib/rlink + - rlink_sp2c.vhd - rlink_core8 + serport_2clock2 combo + - rtl/vlib/serport + - serport_2clock2.vhd - like serport_2clock, use fifo_2c_dram2 + - rtl/vlib/xlib + - usr_access_unisim.vhd - Wrapper for USR_ACCESS* entities + - new files + - tools/bin + - xise_msg_summary - list all filtered ISE messages + - xviv_msg_filter - message filter for vivado + - xviv_msg_summary - list all filtered vivado messages + - xviv_sim_vhdl_cleanup - cleanup vivado generated vhdl for ghdl + - makeise - wrapper for make -f Makefile.ise + - tools/tcl/rbtest + - test_flow.tcl - test back pressure and flow control + +### Changes + + - rtl/bplib/*/*_pins.xdc - add BITSTREAM.CONFIG.USR_ACCESS setup + - rtl/bplib/*/tb/tb_*.vbom - use -UUT attribute + - rtl/sys_gen/*/*/tb/tb_*.vbom - use -UUT attribute + - rtl/make_ise + - generic_ghdl.mk - use ghdl.?sim as workdir for ghdl + - generic_xflow.mk - use .imfset for ISE message rules + - rtl/make_viv + - generic_ghdl.mk - use ghdl.?sim as workdir for ghdl + - generic_vivado.mk - add [sorep]sim.v and %.vivado targets + - vmfset support, use xviv_sim_vhdl_cleanup + - generic_xsim.mk - [rep]sim models; use xsim.?sim as workdir + - viv_tools_build.tcl - use explore flows; prj,opt,pla modes + - viv_tools_config.tcl - add USR_ACCESS readback + - viv_tools_model.tcl - add [sor]sim_vhdl [sorepd]sim_veri modes + - rtl/sys_gen/*/* (all rlink based designs) + - sys_*.vhd - define rlink SYSID + - rtl/sys_gen/*/* (all rlink and 7series based designs) + - sys_*.vhd - add rbd_usracc, use serport_2clock2 + - sys_conf.vhd - use PLL for clkser_gentype + - rtl/sys_gen/w11a/* + - sys_conf.vhd - add sys_conf_cache_twidth + - rtl/sys_gen/tst_serloop/nexys4 + - sys_tst_serloop1_n4.vhd - clock now from cmt and configurable + - rtl/sys_gen/tst_serloop/tb + - tb_tst_serloop.vhd - use serport_(uart_rxtx|xontx)_tb + - rtl/vlib/*/tb/tb_*.vbom - use -UUT attribute + - rtl/vlib/*/tb/tbd_*.vbom - use generic_clk_100mhz.xdc + - rtl/vlib/comlib/comlib.vhd - leave return type unconstraint + - rtl/vlib/simlib/simlib.vhd - add writetimens() + - rtl/w11a + - pdp11_bram_memctl.vhd - use memory inference now + - pdp11_cache.vhd - now configurable size (8,16,32,64,128 kB) + - pdp11_sequencer.vhd - proc_snum conditional (vivado fsm fix) + - rtl/*/*.vbom - use memory inference for vivado + - rtl/*/*.vhd - workarounds and fixes to many FSMs + - tools/bin + - tbrun_tbw - use _bsim.log for behavioral sim log + - tbrun_tbwrri - use _bsim.log for behavioral sim log + use 120 sec timeout for simulation + - tbw - add '-norun', -run now default + - ti_rri - add --tout option + use 120 sec timeout for simulation + - vbomconv - add file properties (-UUT,-SCOPE_REF) + full xsim support now in -vsim_prj + - tools/src/librlink + - RlinkConnect - add USR_ACCESS register support + - tools/src/librlinktpp + - RtclRlinkConnect - add USR_ACCESS, timeout access + - tools/tcl/rbtest + - test_data.tcl - add dinc register tests + - tools/tcl/rlink + - util.tcl - add USR_ACCESS register support + + - removed designs + - rtl/sys_gen/tst_fx2loop/nexys*/*/sys_tst_fx2loop_*_n* + - rtl/sys_gen/tst_rlink_cuff/nexys2/ic3/sys_tst_rlink_cuff_ic3_n2 + - renames + - *.mfset -> *.imfset - to be complementary to new .vmfset + - Makefile -> Makefile.ise - old ISE makefiles in component areas + +### Bug fixes + + - rtl/bplib/arty/tb + - tb_arty.vhd: - add portsel logic + - rtl/bplib/sysmon + - sysmon_rbus_core.vhd - use s_init (and not s_idle) after RESET + - rtl/vlib/xlib + - s7_cmt_sfs_*.vhd - correct mmcm range check boundaries + - tools/bin + - ti_w11: - proper portsel oob for -fx + - tbrun_tbwrri: - proper portsel oob for -hxon + +### Known issues +- all issues: see README_known_issues.txt +- resolved issues: + - **V0.72-1**: since vivado 2016.1 xelab builds models which use DPI in a + mixed vhdl-verilog language environment. + - **V0.72-2**: now full support to build behavioral as well as functional and + timing simulations with xsim. See V.073-1 and 0.73-2 for caveats. + - **V0.64-7**: flow control issues with simulation models resolved + - **V0.64-3**: basys3, nexys4 and arty designs support now 12 MBaud. +- new issues: + - **V0.73-1**: as of vivado 2016.2 `xelab` shows sometimes extremely long + build times, especially for generated post-synthesis vhdl models. But also + building a behavioral simulation for a w11a design can take 25 min. + Even though post-synthesis or post-routing models are now generated + in verilog working with xsim is cumbersome and time consuming. + - **V0.73-2**: Many post-synthesis functional and especially post-routing + timing simulations currently fail due to startup and initialization + problems. Cause is MMCM/PLL startup, which is not properly reflected + in the test bench. Will be resolved in an upcoming release. + - **V0.73-3**: The 'state number generator' code in `pdp11_sequencer` causes + in vivado 2016.1 (and .2) that the main FSM isn't re-coded anymore, which + has high impact on achievable clock rate. The two optional debug units + depending on the state number, `dmscnt` and `dmcmon`, are therefore + currently deactivated in all Artix based systems (but are available on + all Spartan based systems). + + +--- +## 2016-03-19: w11a_V0.72 - svn rev 35(oc) 746(wfjm) +### Preface +- The new low-cost Digilent Arty board is a very attractive platform. + The DDR3 memory will take some time to integrate, in this release thus + only designs using the BRAMs. +- added support for the Vivado simulator. Simple test benches work fine. + Rlink based test benches don't work due to a bug in Vivado 2015.4. +- A rather esoteric CPU bug was fixed in release V0.71 but forgotten to + mention in the README. See [ECO-027-trap_mmu.md](ECO-027-trap_mmu.md) + for details. + +### Summary +- added Arty support. The w11a design uses BRAMs as memory, like the + Basys3 version. This gives 176 KByte memory, not enough for 2.11BSD, + but for many other less demanding OS available for a PDP11. +- added support for SYSMON/XADC (see README_xadc.txt) +- Vivado flow is now default for test benches of components and all Artix + based systems. If applicable an ISE flow is available under Makefile.ise + (resolves known issues V0.64-4 and V0.64-5). +- re-factored tbcore_rlink to support DPI and VHPI +- Vivado supports with DPI (from SystemVerilog) a mechanism to call + external C code. The rlink test bench code so far relies on VHPI, which + is supported by ghdl, but not by ISE ISim or Vivado xsim. The code was + restructured and can use now DPI or VHPI to support both ghdl and + Vivado. Unfortunately has Vivado 2015.4 a bug, DPI doesn't work in a + mixed vhdl-verilog language environment (see Known issues), so the + code base is there, but utilization will habe to wait. +- Vivado synthesis by default keeps hierarchy. This leads to doubly defined + modules if a component is used in both test bench and unit under test. + To avoid this copies of s7_cmt_sfs and some serport_* modules were + created and are now used in the test benches. + +### New features + + - new directory trees for + - rtl/bplib/arty - board support files for arty + - rtl/bplib/sysmon - driver + rbus iface for SYSMON/XADC + - rtl/vlib/rlink/tbcore - new location for rlink tb iface code + - tools/tcl/rbsysmon - sysmon/xadc support + - new modules + - rtl/bplib/bpgen + - rgbdrv_* - driver + rbus iface for 3 color RGBLED + - rtl/vlib/rlink/tbcore + - rlink_cext_iface_dpi.sv - DPI based cext iface + - rlink_cext_iface_vhpi.vhd - VHPI based cext iface + - rlink_cext_dpi.c - dpi to vhpi adapter + - rtl/vlib/serport/tb + - serport_uart_*_tb - added copies for tb usage + - rtl/vlib/xlib/tb + - s7_cmt_sfs_tb - added copy for tb usage + + - new files + - doc/man/man1 + - tbrun_tbw.1 - man file for tbrun_tbw + - tbrun_tbwrri.1 - man file for tbrun_tbwrri + - new systems + - rtl/sys_gen/tst_rlink - rlink tester + - arty/sys_tst_rlink_arty - for Arty + - rtl/sys_gen/w11a - w11a + - arty_bram/sys_w11a_br_arty - for Arty (BRAM only, 176 MByte) + +### Changes + + - */.cvsignore - all ignore files re-organized + - */tb/Makefile - Vivado now default, keep Makefile.ise + - rtl/bplib/*/tb/tb_*.vhd - use s7_cmt_sfs_tb and serport_master_tb + - rtl/vlib/comlib + - comlib.vhd - add work-around for vivado 2015.4 issue + - rtl/vlib/rbus + - rb_sres_or_mon - supports 6 inputs now + - rtl/vlib/serport + - serport_master - moved to tb, _tb appended to name + - rtl/vlib/rlink/tbcore + - tbcore_rlink - re-structured to use rlink_cext_iface + - rtl/sys_gen/... + - sys_tst_rlink_b3 - hardwire XON=1, support XADC + - sys_tst_rlink_n4 - support XADC and RGBLEDs + - sys_w11a_b3 - hardwire XON=1, support XADC; 72 MHz now + - sys_w11a_n4 - support XADC + - tools/bin + - tbrun_tbw - add vivado xsim and Makefile.ise support + - tbrun_tbwrri - use --sxon and --hxon instead of --xon + - tbw - add XSim support + - ti_w11 - add arty support, add -fx + - vbomconv - add [ise,viv]; add @uut tag handling; + add preliminary --(vsyn|vsim)_export; + add vivado xsim support; + - xtwi,xtwv - add BARE_PATH to provide clean environment + +### Bug fixes + + - tools/tcl/rutil + - regdsc.tcl - regdsc: fix variable name in error msg + +### Known issues +- all issues: see README_known_issues.txt +- resolved issues: + - **V0.64-4**: support added for Vivado xsim. See however issue V0.72-1+2. + - **V0.64-5**: w11a_tb_guide.txt covers xsim tests too. + +- new issues: + - **V0.72-1**: Vivado 2015.4 xelab crashes when DPI is used in a mxied + vhdl-verilog language environment. This prevents currently to + build a xsim simulation model for rlink based test benches. + - **V0.72-2**: xsim simulations with timing annotation not yet available. + + +--- +## 2015-12-30: w11a_V0.71 - svn rev 34(oc) 722(wfjm) +### Preface +- the w11a so far lacked any 'hardware debugger' support, which made the + debugging of CPU core issues a bit tedious. This release added a first + implementation of CPU debugger and monitoring features + - `dmhbpt`: hardware break point unit. Allows to set multiple break points + on instruction fetches (thus code break points) and on data + reads/writes (thus data access break points). The number of + breakpoints is configurable between 0 and 4, in current + designs 2 are available + - `dmcmon`: CPU state monitor. A buffer of configurable size which holds + a wide range of information on execution of the most recent + instructions. Tracing can be a instruction as well as on + micro cycle level. + - `dmscnt`: micro state counter. A counter array which allows to monitor + in which micro state the CPU time is spend, separated for + kernel and supervisor/user mode. +- These three units together with the already existing ibus monitor allow + a very detailed and specific monitoring and debugging of the CPU. +- The w11a CPU core is not functionally modified in this release, the only + exception is the suspend logic needed to implement hardware break points. + Both the hardware break point and the instruction level tracing in dmcmon + require a clean definition of instruction boundaries, which the current + w11a core does not provide in some cases. This leads to imprecise + breakpoints (CPU executes one additional instruction) and incomplete + `dmcmon` traces (at instruction level when exceptions are taken). +- The w11a core will be modified in the next release to handle the above + mentioned conditions properly. The dmhbpt and dmcmon will be fully + documented when the w11a core changes are done, they work as expected + under all conditions, and the full back end integration is completed. +- bottom line is that this release has little added value for normal w11 + usage. It is technically necessary to separate the addition of all + the debug units and modification of the CPU core into two releases. + +### Summary +- new reference system + - switched to Vivado 2015.4 (from 2014.4) + Note: 2015.4 has WebPACK support for Logic Analyser and HLS. Both are + not used so far, but the logic analyser may come in handy soon. + - switched to tcl8.6 (from tcl8.5) + Note: tcl8.6 is default tcl in Ubuntu 2014.04LTS, but up to now the + tclshcpp helper was linked against tcl8.5. So far no tcl8.6 + langauge features are used, but may be in future. + +### New features + + - new modules + - rtl/w11a + - pdp11_dmcmon - pdp11: debug&moni: cpu monitor + - pdp11_dmhbpt - pdp11: debug&moni: hardware breakpoint + - pdp11_dmhbpt_unit - pdp11: dmhbpt - individual unit + - pdp11_dmscnt - pdp11: debug&moni: state counter + - new files + - tools/bin + - dmscntanal - analyze dmscnt data + - dmscntconv - convert dmscnt data + - tools/asm-11/lib + - defs_mmu.mac - definitions for mmu registers + - defs_nzvc.mac - definitions for condition code combos + - defs_reg70.mac - definitions for 11/70 CPU registers + - tcode_std_base.mac - Default tcode base code for simple tests + - tcode_std_start.mac - Default tcode startup code + - vec_devcatch.mac - vector catcher for device interrupts + - vec_devcatch_reset.mac - re-write vector catcher + - tools/tbench + - w11a_cmon - directory with dmcmon tests + - w11a_hbpt - directory with dmhbpt tests + - tools/tcl + - ibd_(dl|lp|pc|rk|rl)11 - directory with register regdsc's + - tools/tcl/rutil + - fileio.tcl - new tofile and fromfile procs + - tools/tcl/rw11 + - dmcmon.tcl - support code for dmcmon + - dmhbpt.tcl - support code for dmhbpt + - dmscnt.tcl - support code for dmscnt + - shell.tcl - new w11a tcl shell + - shell_egd.tcl - code for e,g,d commands + - tools/tcl/rw11util + - regmap.tcl - support for 'map of regdsc' definitions + +### Changes + + - rtl/vlib/rlink + - rlink_core.vhd - add proc_sres: strip 'x' from RB_SRES.dout + - rtl/vlib/rlink/tb + - tbcore_rlink - drive SB_CNTL from start to avoid 'U' + - rtl/w11a + - pdp11 - add defs for pdp11_dm(scnt|hbpt|cmon) + - pdp11_* - add support for pdp11_dm(scnt|hbpt|cmon) + - rtl/sys_gen/w11a/* + - sys_conf - add sys_conf_(dmscnt|dmhbpt*|dmcmon*) + - rtl/sys_gen/w11a/*/tb + - sys_conf_sim - add sys_conf_(dmscnt|dmhbpt*|dmcmon*) + - tools/bin/ + - ti_w11 - add -ghw option + - tmuconv - fix '.' handling for br/sob instructions + correct xor (now r,dst, and not src,r) + - tools/tcl/rutil + - regdsc.tcl - add regbldkv,reggetkv + - util.tcl - rename optlist2arr->args2opts, new logic + - tools/tcl/rw11 + - asm.tcl - new arg list format in asm(run|treg|tmem) + - dasm.tcl - add dasm_inst2txt + - tools/tcl/ibd_ibmon + - util.tcl - add symbolic register dump + +### Bug fixes + + - rtl/bplib/micron + - mt45w8mw16b - fix issue when 1st access is to addr 0 + - rtl/bplib/nxcramlib + - nx_cram_memctl_as - always define imem_oe in do_dispatch() + - rtl/ibus + - ibdr_tm11 - add missing BESET to sensitivity list + - rtl/w11a + - pdp11_sequencer - proper trap_mmu and trap_ysv handling + - tools/bin + - asm-11 - fix '.' handling in instructions + +### Known issues +- all issues: see README_known_issues.txt diff --git a/doc/CHANGELOG.md b/doc/CHANGELOG.md new file mode 100644 index 00000000..6b8c0e66 --- /dev/null +++ b/doc/CHANGELOG.md @@ -0,0 +1,16 @@ +# Changelog: w11a_V0.74 -> master + +### Table of contents +- Current [master](#user-content-master) + +- [CHANGELOG for w11a_V.70 to w11a_V0.74.md](CHANGELOG-w11a_V.70-w11a_V0.74.md) +- [CHANGELOG for w11a_V.60 to w11a_V0.70.md](CHANGELOG-w11a_V.60-w11a_V0.70.md) +- [CHANGELOG for w11a_V.50 to w11a_V0.60.md](CHANGELOG-w11a_V.50-w11a_V0.60.md) + + +--- +## master + +### Summary +- converted documentation from plain text to markdown + diff --git a/doc/ECO-026-div.md b/doc/ECO-026-div.md new file mode 100644 index 00000000..4f500733 --- /dev/null +++ b/doc/ECO-026-div.md @@ -0,0 +1,114 @@ +# ECO-026: `div` instruction fix (2014-08-08) + +### Scope +- Introduced in release w11a_V0.61 +- Affects: all w11a systems + +### Symptom summary +The div instruction gave wrong results in some corner cases when either +divisor or quotient were the largest negative integer (100000 or -32768): + 1. wrong q and r when dd=n*(-32768), dr=-32768 with n even + 2. V=1 set when division solvable and proper result is q=-32768 + +### Background +The PDP-11/70 (KB11-C) and the w11a use very different division algorithms. +Both use a non-restoring divide. +- The KB11-C uses a straight forward 2 quadrant core algorithm for positive + dividends and positive or negative divisors. Negative dividends are first + converted to positive, the results later corrected. This leads to quite + complex implementation with 35 micro states. +- The w11a uses a 4 quadrant algorithm which directly allows positive and + negative dividends and divisors. The qbit logic is much more complex in + this case. Advantage is that the whole divide algorithm can be implemented + with only 6 states in the main sequencer. + +In twos complement integer arithmetic, as used in the pdp11 and almost all +contemporary computers, the range of positive and negative numbers is +different, for 16 bit for example + + oct 100000 to 077777 + dec -32768 to +32767 + +so the smallest negative number has no positive counterpart. Trying to negate +the smallest negative number leads to the same number + + mov #100000, r0 + neg r0 --> r0 = 100000; V=1 + +These special properties of the largest negative number easily lead to corner +cases which require special treatment, both the KB11-C and the w11a divide +algorithms need special rules and checks for this. + +### Summary of issues +1. when dividend was dd=n*(-32768) with an even n and the divisor was + dr=-32768 the old w11a algorithm returned wrong quotient and remainder + values and V=0 status. +2. for all divisions which result in a quotient of -32768 the old w11a + algorithm set the overflow (V=1) condition. Since in this case the + destination registers were not updated and still contained the + dividend, software not checking the V code saw wrong quotient and + remainder values. + +### Fixes +- Issue 1: wrong q and r for dd=n*(-32768), dr=-32768 with n even. + - the corner case is detected in state s_opg_div by testing that divisor + is 0100000 and low order part of dividend is zero. When detected, the + qbit logic is modified and quotient and remainder corrections are done + unconditionally. + +- Issue 2: V=1 set when division solvable and proper result is q=-32768. + The divide core algorithm calculates the correct q and r, only the + overflow testing was incorrect. + The old algorithm had two overflow abort conditions + - a check that bit 31 and 30 of the dividend are equal + - a check after the first division cycle + The new algorithm now has three overflow abort conditions + - the bit 31/30 check on the dividend was too restrictive. Valid divisions + with dd=(-32768)*(-32768)+n and dr=-32768 giving q=-32768 and r=n would + be rejected. The 31/30 check is now only applied when the divisor is not + equal 0100000 + - the division abort condition in the first division cycle was completely + revised, this avoids that solvable divisions are aborted at this stage + - the first two conditions don't catch all overflow situations. The + remaining ones all have after the quotient correction stage q>0 when + a negative quotient is expected. A third overflow check was added to + s_opg_div_sr to handle these cases. + +### Side effects +- the old implementation guaranteed that the destination registers were + unchanged in case of overflow. The new does not, the overflow check in + `s_opg_div_sr` is done after the quotient is stored, and storing remainder + is not suppressed in case of overflow. So both q and r regs are changed. +- with additional states it could be guaranteed that destination registers + are never updated in case of overflow. See proviso below. +- the pdp-11/70 KB11-C in most cases keeps destination registers unchanged + in case of overflow, but also has a late check after one register has + been modified. +- the J11 never updates registers in case of overflow. A case like + 0,177777 / 177777 were w11a now updates regs is known from J11 + diagnostics to not update in J11. +- simh always preserves the destination registers in case of overflow. + +**The pdp11 processor handbook considers the destination registers as** +**undefined in case of division overflow, so the w11a behavior is OK.** + +### Provisos +- the behavior after V=1 aborts of a div instruction is now different in + + ``` + w11a --> regs updated under some rare conditions + KB11-C --> regs updated under some rare conditions + but in cases different from w11a + 11/44 --> regs updated under some conditions (see v7_longdivide_bug.txt) + J11 --> regs never updated + simh --> regs never updated + ``` + - that can lead to spurious failures in original DEC diagnostics when + they test the complete response + - even though the current w11a behavious is full within specs it is unclear + whether all software tolerates this, especially non-DEC OS. Unix V7 is + known to have an issue with ldiv and CPUs not preserving regs, see + http://minnie.tuhs.org/PUPS/v7_longdivide_bug.txt + - Only further studes can show whether it is worth the effort and the + slow down of 1-2 cycles to guarantee preserved registers. + diff --git a/doc/ECO-026-div.txt b/doc/ECO-026-div.txt deleted file mode 100644 index f8d94aef..00000000 --- a/doc/ECO-026-div.txt +++ /dev/null @@ -1,108 +0,0 @@ -$Id: ECO-026-div.txt 579 2014-08-08 20:39:46Z mueller $ - -Scope: - Introduced in release w11a_V0.61 - Affects: all w11a systems - -Symptom summary: - The div instruction gave wrong results in some corner cases when either - divisor or quotient were the largest negative integer (100000 or -32768): - 1. wrong q and r when dd=n*(-32768), dr=-32768 with n even - 2. V=1 set when division solvable and proper result is q=-32768 - -Background: - The PDP-11/70 (KB11-C) and the w11a use very different division algorithms. - Both use a non-restoring divide. - - The KB11-C uses a straight forward 2 quadrant core algorithm for positive - dividends and positive or negative divisors. Negative dividends are first - converted to positive, the results later corrected. This leads to quite - complex implementation with 35 micro states. - - The w11a uses a 4 quadrant algorithm which directly allows positive and - negative dividends and divisors. The qbit logic is much more complex in - this case. Advantage is that the whole divide algorithm can be implemented - with only 6 states in the main sequencer. - - In twos complement integer arithmetic, as used in the pdp11 and almost all - contemporary computers, the range of positive and negative numbers is - different, for 16 bit for example - oct 100000 to 077777 - dec -32768 to +32767 - so the smallest negative number has no positive counterpart. Trying to negate - the smallest negative number leads to the same number - mov #100000, r0 - neg r0 --> r0 = 100000; V=1 - - These special properties of the largest negative number easily lead to corner - cases which require special treatment, both the KB11-C and the w11a divide - algorithms need special rules and checks for this. - -Summary of issues: - 1. when dividend was dd=n*(-32768) with an even n and the divisor was - dr=-32768 the old w11a algorithm returned wrong quotient and remainder - values and V=0 status. - 2. for all divisions which result in a quotient of -32768 the old w11a - algorithm set the overflow (V=1) condition. Since in this case the - destination registers were not updated and still contained the - dividend, software not checking the V code saw wrong quotient and - remainder values. - -Fixes: - - Issue 1: wrong q and r for dd=n*(-32768), dr=-32768 with n even. - - the corner case is detected in state s_opg_div by testing that divisor - is 0100000 and low order part of dividend is zero. When detected, the - qbit logic is modified and quotient and remainder corrections are done - unconditionally. - - - Issue 2: V=1 set when division solvable and proper result is q=-32768. - The divide core algorithm calculates the correct q and r, only the - overflow testing was incorrect. - The old algorithm had two overflow abort conditions - - a check that bit 31 and 30 of the dividend are equal - - a check after the first division cycle - The new algorithm now has three overflow abort conditions - - the bit 31/30 check on the dividend was too restrictive. Valid divisions - with dd=(-32768)*(-32768)+n and dr=-32768 giving q=-32768 and r=n would - be rejected. The 31/30 check is now only applied when the divisor is not - equal 0100000 - - the division abort condition in the first division cycle was completely - revised, this avoids that solvable divisions are aborted at this stage - - the first two conditions don't catch all overflow situations. The - remaining ones all have after the quotient correction stage q>0 when - a negative quotient is expected. A third overflow check was added to - s_opg_div_sr to handle these cases. - -Side effects: - - the old implementation guaranteed that the destination registers were - unchanged in case of overflow. The new does not, the overflow check in - s_opg_div_sr is done after the quotient is stored, and storing remainder - is not suppressed in case of overflow. So both q and r regs are changed. - - with additional states it could be guaranteed that destination registers - are never updated in case of overflow. See proviso below. - - the pdp-11/70 KB11-C in most cases keeps destination registers unchanged - in case of overflow, but also has a late check after one register has - been modified. - - the J11 never updates registers in case of overflow. A case like - 0,177777 / 177777 were w11a now updates regs is known from J11 - diagnostics to not update in J11. - - simh always preserves the destination registers in case of overflow. - - !! the pdp11 processor handbook considers the destination registers as !! - !! undefined in case of division overflow, so the w11a behavior is OK. !! - -Provisos: - - the behavior after V=1 aborts of a div instruction is now different in - - w11a --> regs updated under some rare conditions - - KB11-C --> regs updated under some rare conditions - but in cases different from w11a - - 11/44 --> regs updated under some conditions (see v7_longdivide_bug.txt) - - J11 --> regs never updated - - simh --> regs never updated - --> that can lead to spurious failures in original DEC diagnostics when - they test the complete response - --> even though the current w11a behavious is full within specs it is unclear - whether all software tolerates this, especially non-DEC OS. Unix V7 is - known to have an issue with ldiv and CPUs not preserving regs, see - http://minnie.tuhs.org/PUPS/v7_longdivide_bug.txt - --> Only further studes can show whether it is worth the effort and the - slow down of 1-2 cycles to guarantee preserved registers. - diff --git a/doc/ECO-027-trap_mmu.md b/doc/ECO-027-trap_mmu.md new file mode 100644 index 00000000..72e5dcde --- /dev/null +++ b/doc/ECO-027-trap_mmu.md @@ -0,0 +1,47 @@ +# ECO-027: trap_mmu fix (2015-12-30) + +### Scope +- Introduced in release w11a_V0.71 +- Affects: all w11a systems + +### Symptom summary + A mmu trap could be lost or vectored through 014 (bpt) rather 250 (mmu). + +### Background +The PDP-11/70 and 11/45 MMU offers a 'mmu trap' feature, which can cause +a trap when a memory location is read or written. This can be enabled with +special `ACF` values in the page descriptor registers for each segment end +globally enabled with an enable bit in `SSR0`. + +Since only 11/70 and 11/45 offer this (and J11 does not) this feature is +in general not used by operations systems. + +Summary of issues: +When an instruction does more than one memory access and the mmu trap +condition occurs not on the last access +- an mmu trap could be missed +- an mmu trap might be vectored through 014 (the bpt vector) +The later happens for all read-modify-write accesses. + +### Analysis +The `VM_STAT.trap_mmu` flag was copied into the `R_STATUS.trap_mmu` state bit +in `do_memcheck`, which is called for each memory wait. In case of a +read-modify-write the initial read will signal `trap_mmu`, while the +rmw completion will not (the mmu doesn't check on rmw completions). +This leads to +- lost mmu traps (e.g. when mmu trap comes on 1st of 2 access) +- mmu traps vectored through 014 (the bpt vector) + +The later happens due to the logic of state `s_opg_gen_rmw_w`: +- `do_memcheck` can clear `R_STATUS.trap_mmu` +- `do_fork_next` still branches to `s_trap_disp` because `R_STATUS.trap_mmu='1'` +- `s_trap_disp` sees `R_STATUS.trap_mmu='0'` and miscalculates the vector + +### Fixes +`pdp11_sequencer` was modified to ensure that `R_STATUS.trap_mmu` is only set +in `do_memcheck`. Same for `trap_ysv` (which had the same potential bug) + +### Provisos +The issue was found by systematic testing of mmu fault and trap behavior. +Because known OS don't use mmu traps the issue should not have any impact +on practical usage with OS like rsx or 211bsd. diff --git a/doc/ECO-027-trap_mmu.txt b/doc/ECO-027-trap_mmu.txt deleted file mode 100644 index 93223772..00000000 --- a/doc/ECO-027-trap_mmu.txt +++ /dev/null @@ -1,46 +0,0 @@ -$Id: ECO-027-trap_mmu.txt 708 2015-08-03 06:41:43Z mueller $ - -Scope: - Introduced in release w11a_V0.71 - Affects: all w11a systems - -Symptom summary: - A mmu trap could be lost or vectored through 014 (bpt) rather 250 (mmu). - -Background: - The PDP-11/70 and 11/45 MMU offers a 'mmu trap' feature, which can cause - a trap when a memory location is read or written. This can be enabled with - special ACF values in the page descriptor registers for each segment end - globally enabled with an enable bit in SSR0. - - Since only 11/70 and 11/45 offer this (and J11 does not) this feature is - in general not used by operations systems. - -Summary of issues: - When an instruction does more than one memory access and the mmu trap - condition occurs not on the last access - - an mmu trap could be missed - - an mmu trap might be vectored through 014 (the bpt vector) - The later happens for all read-modify-write accesses. - -Analysis: - The VM_STAT.trap_mmu flag was copied into the R_STATUS.trap_mmu state bit - in do_memcheck, which is called for each memory wait. In case of a - read-modify-write the initial read will signal trap_mmu, while the - rmw completion will not (the mmu doesn't check on rmw completions). - This leads to - - lost mmu traps (e.g. when mmu trap comes on 1st of 2 access) - - mmu traps vectored through 014 (the bpt vector) - The later happens due to the logic of state s_opg_gen_rmw_w: - - do_memcheck can clear R_STATUS.trap_mmu - - do_fork_next still branches to s_trap_disp because R_STATUS.trap_mmu='1' - - s_trap_disp sees R_STATUS.trap_mmu='0' and miscalculates the vector - -Fixes: - pdp11_sequencer was modified to ensure that R_STATUS.trap_mmu is only set - in do_memcheck. Same for trap_ysv (which had the same potential bug) - -Provisos: - The issue was found by systematic testing of mmu fault and trap behavior. - Because known OS don't use mmu traps the issue should not have any impact - on practical usage with OS like rsx or 211bsd. diff --git a/doc/FILES.txt b/doc/FILES.txt deleted file mode 100644 index d8188873..00000000 --- a/doc/FILES.txt +++ /dev/null @@ -1,71 +0,0 @@ -$Id: FILES.txt 681 2015-05-14 17:37:00Z mueller $ - -Short description of the directory layout, what is where ? - - doc Documentation - doc/man man pages for retro11 commands - rtl VHDL sources - rtl/bplib - board and component support libs - rtl/bplib/atlys - for Digilent Atlys board - rtl/bplib/basys3 - for Digilent Basys3 board - rtl/bplib/fx2lib - for Cypress FX2 USB interface controller - rtl/bplib/issi - for ISSI parts - rtl/bplib/micron - for Micron parts - rtl/bplib/nexys2 - for Digilent Nexsy2 board - rtl/bplib/nexys3 - for Digilent Nexsy3 board - rtl/bplib/nexys4 - for Digilent Nexsy4 board - rtl/bplib/nxcramlib - for CRAM part used in Nexys2/3 - rtl/bplib/s3board - for Digilent S3board - rtl/ibus - ibus devices (UNIBUS peripherals) - rtl/sys_gen - top level designs - rtl/sys_gen/tst_fx2loop - top level designs for Cypress FX2 tester - nexys2,nexys3 - systems for Nexsy2,Nexsy3 - rtl/sys_gen/tst_rlink - top level designs for an rlink tester - nexys2,nexys3,s3board - systems for Nexsy2,Nexsy3,S3board - basys3,nexys4 - systems for Basys3,Nexys4 - rtl/sys_gen/tst_rlink_cuff - top level designs for rlink over FX2 tester - nexys2,nexys3,atlys - systems for Atlys,Nexsy2,Nexsy3 - rtl/sys_gen/tst_serloop - top level designs for serport loop tester - nexys2,nexys3,s3board - systems for Nexsy2,Nexsy3,S3board - nexys4 - systems for Nexys4 - rtl/sys_gen/tst_snhumanio - top level designs for human I/O tester - atlys,nexys2,nexys3,s3board - systems for Atlys,Nexsy2,Nexsy3,S3board - basys3,nexys4 - systems for Basys3,Nexys4 - rtl/sys_gen/w11a - top level designs for w11a SoC - nexys2,nexys3,s3board - w11a systems for Nexsy2,Nexsy3,S3board - basys3,nexys4 - systems for Basys3,Nexys4 - rtl/vlib - VHDL component libs - rtl/vlib/comlib - communication - rtl/vlib/genlib - general - rtl/vlib/memlib - memory - rtl/vlib/rbus - rri: rbus - rtl/vlib/rlink - rri: rlink - rtl/vlib/serport - serial port (UART) - rtl/vlib/simlib - simulation helper lib - rtl/vlib/xlib - Xilinx specific components - rtl/w11a - w11a core - tools helper programs - tools/asm-11 - pdp-11 assembler code - tools/asm-11/lib - definitions and macros for asm-11 - tools/asm-11/tests - test bench for asm-11 - tools/asm-11/tests-err - test bench for asm-11 (error check part) - tools/bin - scripts and binaries - tools/dox - Doxygen documentation configuration - tools/make_ise - make includes for ISE - tools/make_viv - make includes for Vivado - tools/fx2 - Firmware for Cypress FX2 USB Interface - tools/fx2/bin - pre-build firmware images in .ihx format - tools/fx2/src - C and asm sources - tools/fx2/sys - udev rules for USB on fpga eval boards - tools/oskit - setup files for Operation System kits - tools/oskit/... - several PDP-11 system kits available - tools/src - C++ sources for rlink backend software - tools/src/librlink - basic rlink interface - tools/src/librlinktpp - C++ to tcl binding for rlink interface - tools/src/librtcltools - support classes to implement Tcl bindings - tools/src/librtools - general support classes and methods - tools/src/librutiltpp - Tcl support commands implemented in C++ - tools/src/librw11 - w11 over rlink interface - tools/src/librwxxtpp - C++ to tcl binding for w11 over rlink iface - tools/tbench - w11 CPU test bench - tools/tcl - Tcl scripts diff --git a/doc/INSTALL.md b/doc/INSTALL.md new file mode 100644 index 00000000..c96b9ec4 --- /dev/null +++ b/doc/INSTALL.md @@ -0,0 +1,301 @@ +# Guide to install and build w11a systems, test benches and support software + +### Table of content + +- [Download](#user-content-download) +- [System requirements](#user-content-sysreq) +- [Setup environment variables](#user-content-envvar) +- [Compile UNISIM/UNIMACRO/SIMPRIM libraries for ghdl](#user-content-ghdl-lib) +- [Compile and install the support software](#user-content-build-tools) + - [Compile sharable libraries](#user-content-build-cpp) + - [Setup Tcl packages](#user-content-build-tcl) +- [The build system](#user-content-build-system) +- [Available designs](#user-content-build-fpga) +- [Available bitkits with bit and log files](#user-content-bitkits) +- [Generate Doxygen based source code view](#user-content-build-doxy) + +### Download + +All instructions below assume that the project files reside in a +working directory with the name represented as `` + +- to download the repository + + git clone https://github.com/wfjm/w11 + +- use the latest snapshop under `master` + + cd + git checkout master + +- to use tagged verions list available tags + + cd + git tag -l + + and select one of them + + cd + git checkout tags/ + +The GitHub repository contains the full version history since 2010. +Prior to October 2016 the project was maintained on OpenCores, access +to the legacy svn repository is described in +[INSTALL_from_opencores.md](INSTALL_from_opencores.md). + +### System requirements + +This project contains not only VHDL code but also support software. Therefore +quite a few software packages are expected to be installed. The following +list gives the Ubuntu/Debian package names, but mapping this to other +distributions should be straight forward. + +- building the FPGA bit files requires the Xilinx design tools + - Vivado WebPACK (for Artix-7 based designs) + - ISE WebPACK (for Spartan-3 and Spartan-6 based designs) +- building and using the rlink backend software requires: + - full C/C++ development chain (gcc,g++,cpp,make) + -> package: `build-essential` + - Boost C++ library (>= 1.40), with date-time, thread, and regex + -> package: `libboost-dev` `libboost-date-time-dev` `libboost-thread-dev` + `libboost-regex-dev` + - libusb 1.0 (>= 1.0.6) + -> package: `libusb-1.0-0-dev` + - Perl (>= 5.10) (usually included in base installations) + - Tcl (>= 8.6), with tclreadline support + -> package: `tcl` `tcl-dev` `tcllib` `tclreadline` + +- for VHDL simulations one needs + - ghdl + -> see [INSTALL_ghdl.md](INSTALL_ghdl.md) for the unfortunately gory details + - gtkwave + -> package: `gtkwave` + +- additional requirements for using Cypress FX (on Nexys2/3) see + [INSTALL_fx2_support.md](INSTALL_fx2_support.md). + +- for doxygen documentation an up-to-date installation of doxygen is + required, version 1.8.3.1 or later + + +### Setup environment variables + +The make flows for building test benches (ghdl, Vivado xsim or ISE ISim based) +and FPGA bit files (with Vivado or ISE) as well as the support software +(mainly the rlink backend server) requires the definition of the environment +variables: + +| Variable | Comment | +| :------- | :------ | +| `RETROBASE` | must refer to the installation root directory | +| `PATH` | the tools binary directory `$RETROBASE/tools/bin` must be in the path | +| `LD_LIBRARY_PATH` | the tools library directory `$RETROBASE/tools/lib` must be in the library path | +| `MANPATH` | the tools man page directory `$RETROBASE/tools/man` should be in the man path | +| `TCLINC` | pathname for includes of Tcl runtime library | +| `TCLLIBNAME` | name of Tcl runtime library | +| `RETRO_FX2_VID` | default USB VID, see below | +| `RETRO_FX2_PID` | default USB PID, see below | +| `TCLLIB` | pathname for libraries of Tcl _(optional)_ | +| `BOOSTINC` | pathname for includes of boost library _(optional)_ | +| `BOOSTLIB` | pathname for libraries of boost library _(optional, `BOOSTINC` and `BOOSTLIB` must be either both defined or both undefined)_ | + +For bash and alike use + + export RETROBASE= + export PATH=$PATH:$RETROBASE/tools/bin + export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$RETROBASE/tools/lib + export MANPATH=$MANPATH:$RETROBASE/tools/man + +In most cases the boost library version coming with the distribution will +work, similar for Tcl, in those cases simply use + + export TCLINC=/usr/include/tcl8.6 + export TCLLIBNAME=tcl8.6 + +and don't setup `BOOSTINC` and `BOOSTLIB`. + +After that building functional model based test benches will work. If you +want to also build post-synthesis or post-place&route test benches +read next section. + +For Cypress FX2 (on Nexys2/3) related setup see +[INSTALL_fx2_support.md](INSTALL_fx2_support.md). + +### Compile UNISIM/UNIMACRO/SIMPRIM libraries for ghdl + +The build system for test benches also supports test benches run against the +gate level models derived after synthesis or place&route. In this case ghdl +has to link against a compiled a `UNISIM`, `UNIMACRO` or `SIMPRIM` library. +The details are described in +- [README_buildsystem_Vivado.md](README_buildsystem_Vivado.md#user-content-ghdllibs) +- [README_buildsystem_ISE.md](README_buildsystem_ISE.md#user-content-ghdllibs) + +### Compile and install the support software + +#### Compile sharable libraries + +Note: some `c++11` features are used in the code + +| Feature | Description | in gcc since | +| :------ | :---------- | :----------: | +| N2343 | decltype (used by boost bind) | gcc 4.3 | +| N2431 | nullptr | gcc 4.6 | +| N2930 | range based for | gcc 4.6 | +| N1984 | auto-types variables | gcc 4.4 | + +Required tools and libraries: + + g++ >= 4.6 (see c++11 usage above) + boost >= 1.35 (boost::thread api changed, new one is used) + linusb >= 1.0.5 (timerfd support) + +Build was tested under: + + ubuntu precise (14.04 LTS): gcc 4.8.2 boost 1.54 libusb 1.0.17 + debian wheezy (7.0.8): gcc 4.7.2 boost 1.49 libusb 1.0.11 + +To build all sharable libraries + + cd $RETROBASE/tools/src + make -j 4 + +Default is to compile with `-O2` and without `-g`. These options can be +overwritten with the `CXXOPTFLAGS` enviromnent variable (or make opion). +To build with `-O3` optimize use + + make -j 4 CXXOPTFLAGS=-O3 + +To build a debug version with full symbol table use + + make -j 4 CXXOPTFLAGS=-g + +To cleanup, e.g. before a re-build + + cd $RETROBASE/tools/src + rm_dep + make realclean + +#### Setup Tcl environment + +The Tcl files are organized in several packages. To create the Tcl +package files (`pkgIndex.tcl`) + + cd $RETROBASE/tools/tcl + setup_packages + +To use these packages it is convenient to make them available via the +'auto_path' mechanism. To do that add in your `.tclshrc` or `.wishrc` + + lappend auto_path [file join $env(RETROBASE) tools tcl] + lappend auto_path [file join $env(RETROBASE) tools lib] + +The w11 project contains two ready to use `.tclshrc` or `.wishrc` +files which +- include the auto_path statements above +- activate `tclreadline` (and thus in `tclshrc` an event loop) + +To use them simply copy them into your home directory (or soft link them) + + cd $HOME + ln -s $RETROBASE/tools/tcl/.tclshrc . + ln -s $RETROBASE/tools/tcl/.wishrc . + +### The build system + +The generation of FPGA firmware and test benches is based on make flows. + +All details on +- building test benches +- building FPGA bit files +- configuring FPGAs + +can be found under +- [README_buildsystem_Vivado.md](README_buildsystem_Vivado.md) + for Artix-7 based designs +- [README_buildsystem_ISE.md](README_buildsystem_ISE.md) + for Spartan-3 and Spartan-6 based designs + +### Available designs + +Ready to build designs are organized in the directories + + $RETROBASE/rtl/sys_gen// + + with + w11a w11a system + tst_rlink rlink over serial link tester + tst_rlink_cuff rlink over FX2 interface tester + + and + basys3 b3: Digilent Basys3 board + nexys4 n4: Digilent Nexys4 board (cellular RAM version) + nexys3 n3: Digilent Nexys3 board + nexys2 n2: Digilent Nexys2 board (-1200 FPGA version) + s3board s3: Digilent S3board (-1000 FPGA version) + +To build the designs locally use + + cd $RETROBASE/rtl/sys_gen// + make sys__.bit + +with in most cases +- `` = `` +- `` = 2 letter abbreviation for the board, e.g. n4 for nexys4. + +### Available bitkits with bit and log files + +Tarballs with ready to use bit files and all logfiles from the tool +chain can be downloaded from +http://www.retro11.de/data/oc_w11/bitkits/ . + +This area is organized in folders for different releases. The tarball +file names contain information about release, Xlinix tool, and design: + + __.tgz + +- Vivado based designs: + These designs can be loaded with the Vivado hardware server into the FPGA. + +- ISE based designs: + These designs can be loaded with `config_wrapper` into the FPGA. The + procedures for the supported boards are given below. + + Notes: + 1. `XTWI_PATH` and `RETROBASE` environment variables must be defined. + 2. `config_wrapper bit2svf` is only needed once to create the svf files. + 3. fx2load_wrapper is needed once after each board power on. + + - for Digilent Nexys3 board (using Cypress FX2 USB controller) + + xtwi config_wrapper --board=nexys3 bit2svf .bit + fx2load_wrapper --board=nexys3 + xtwi config_wrapper --board=nexys3 jconfig .svf + + - for Digilent Nexys2 board (using Cypress FX2 USB controller) + + xtwi config_wrapper --board=nexys2 bit2svf .bit + fx2load_wrapper --board=nexys2 + xtwi config_wrapper --board=nexys2 jconfig .svf + + - for Digilent S3board (using ISE Impact) + + xtwi config_wrapper --board=s3board iconfig .bit + +### Generate Doxygen based source code view + +Currently there is not much real documentation included in the source +files. The doxygen generated html output is nevertheless very useful +to browse the code. C++, Tcl and Vhdl source are covered by setup files +contained in the project files. + +To generate the html files + + cd $RETROBASE/tools/dox + export RETRODOXY + ./make_doxy + +If `RETRODOXY` is not defined `/tmp` is used. To view the docs use + + firefox $RETRODOXY/w11/cpp/html/index.html & + firefox $RETRODOXY/w11/tcl/html/index.html & + firefox $RETRODOXY/w11/vhd/html/index.html & diff --git a/doc/INSTALL.txt b/doc/INSTALL.txt deleted file mode 100644 index 8dbf8420..00000000 --- a/doc/INSTALL.txt +++ /dev/null @@ -1,322 +0,0 @@ -# $Id: INSTALL.txt 722 2015-12-30 19:45:46Z mueller $ - -Guide to install and build w11a systems, test benches and support software - - Table of content: - - 1. Download - 2. System requirements - 3. Setup environment variables - 4. Compile UNISIM/SIMPRIM libraries for ghdl - 5. Compile and install the support software - a. Compile sharable libraries - b. Setup Tcl packages - 6. The build system - 7. Building test benches - 8. Building systems - d. Available systems - e. Available bitkits with bit and log files - 9. Generate Doxygen based source code view - -1. Download --------------------------------------------------------------- - - All instructions below assume that the project files reside in a - working directory with the name represented as - - - to download latest snapshot of trunk - - cd - svn co http://opencores.org/ocsvn/w11/w11/trunk - - - to download tagged verions (from major releases) - list available svn tags - - svn ls http://opencores.org/ocsvn/w11/w11/tags - - and download one of them - - cd - svn co http://opencores.org/ocsvn/w11/w11/tags/ - - - to download specific svn revision (from minor releases) - determine desired svn revsion from list given on - http://opencores.org/project,w11,overview - - and download - - cd - svn co -r http://opencores.org/ocsvn/w11/w11/trunk - -2. System requirements ---------------------------------------------------- - - This project contains not only VHDL code but also support software. Therefore - quite a few software packages are expected to be installed. The following - list gives the Ubuntu/Debian package names, but mapping this to other - distributions should be straight forward. - - - building the bit files requires a Xilinx ISE WebPACK installation - - - building and using the RLink backend software requires: - - full C/C++ development chain (gcc,g++,cpp,make) - -> package: build-essential - - Boost C++ library (>= 1.40), with date-time, thread, and regex - -> package: libboost-dev libboost-date-time-dev libboost-thread-dev - libboost-regex-dev - - libusb 1.0 (>= 1.0.6) - -> package: libusb-1.0-0-dev - - Perl (>= 5.10) (usually included in base installations) - - Tcl (>= 8.6), with tclreadline support - -> package: tcl tcl-dev tcllib tclreadline - - - for VHDL simulations one needs - - ghdl - -> see INSTALL_ghdl.txt for the unfortunately gory details - - - additional requirements for using Cypress FX (on Nexys2/3) see - INSTALL_fx2_support.txt - - - for doxygen documentation an up-to-date installation of doxygen is - required, version 1.8.3.1 or later - - - optional but very useful is: - - gtkwave - -> package: gtkwave - -3. Setup environment variables -------------------------------------------- - - The make flow for building test benches (ghdl and ISim based) and systems - (Xilinx ISE xst based) as well as the support software (mainly the rlink - backend server) requires - - - the definition of the environment variables: - - RETROBASE: must refer to the installation root directory - - TCLINC: pathname for includes of Tcl runtime library - - TCLLIBNAME: name of Tcl runtime library - - RETRO_FX2_VID and RETRO_FX2_PID: default USB VID/PID, see below - - that the tools binary directory is in the path - - that the tools library directory is in the library path - - optional environment variables: - - TCLLIB: pathname for libraries of Tcl - - BOOSTINC: pathname for includes of boost library - - BOOSTLIB: pathname for libraries of boost library - {Note: Either both must be undefined, or both must be defined} - - For bash and alike use - - export RETROBASE= - export PATH=$PATH:$RETROBASE/tools/bin - export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$RETROBASE/tools/lib - - To access the man pages update also the MANPATH - - export MANPATH=$MANPATH:$RETROBASE/doc/man - - In most cases the boost library version coming with the distribution will - work, similar for Tcl, in those cases simply use - - export TCLINC=/usr/include/tcl8.6 - export TCLLIBNAME=tcl8.6 - - and don't setup BOOSTINC and BOOSTLIB. - - After that building functional model based test benches will work. If you - want to also build post-xst or post-par test benches read next section. - - For Cypress FX2 (on Nexys2/3) related setup see INSTALL_fx2_support.txt - -4. Compile UNISIM/SIMPRIM libraries for ghdl ------------------------------ - - The build system for test benches also supports test benches run against - the gate level models derived after the xst, map or par step. In this - case ghdl has to link against a compiled UNISIM or SIMPRIM library. - - To make handling of the parallel installion of several ISE WebPack versions - easy the compiled libraries are stored in sub-directories under $XILINX: - - $XILINX/ghdl/unisim - $XILINX/ghdl/simprim - - Two helper scripts will create these libraries: - - - - cd $RETROBASE - xise_ghdl_unisim - xise_ghdl_simprim - - If you have several WebPack versions installed, repeat for each version. - -5. Compile and install the support software ------------------------------- - -5a. Compile sharable libraries --------------------------------------- - - Note: some c++11 features are used in the code - - N2343: decltype (used by boost bind) -> since gcc 4.3 - - N2431: nullptr -> since gcc 4.6 - - N2930: range based for -> since gcc 4.6 - - N1984: auto-types variables -> since gcc 4.4 - - Required tools and libraries: - g++ >= 4.6 (see c++11 usage above) - boost >= 1.35 (boost::thread api changed, new one is used) - linusb >= 1.0.5 (timerfd support) - - Build was tested under: - ubuntu precise (14.04 LTS): gcc 4.8.2 boost 1.54 libusb 1.0.17 - debian wheezy (7.0.8): gcc 4.7.2 boost 1.49 libusb 1.0.11 - - To build all sharable libraries - - cd $RETROBASE/tools/src - make -j 4 - - Default is to compile with -O2 and without -g. These options can be - overwritten with the CXXOPTFLAGS enviromnent variable (or make opion). - To build with -O3 optimize use - make -j 4 CXXOPTFLAGS=-O3 - To build a debug version with full symbol table use - make -j 4 CXXOPTFLAGS=-g - - To cleanup, e.g. before a re-build - - cd $RETROBASE/tools/src - rm_dep - make realclean - -5b. Setup Tcl environment -------------------------------------------- - - The Tcl files are organized in several packages. To create the Tcl - package files (pkgIndex.tcl) - - cd $RETROBASE/tools/tcl - setup_packages - - To use these packages it is convenient to make them available via the - 'auto_path' mechanism. To do that add in your .tclshrc or .wishrc - - lappend auto_path [file join $env(RETROBASE) tools tcl] - lappend auto_path [file join $env(RETROBASE) tools lib] - - The w11 distribution contains two ready to use .tclshrc or .wishrc - files which - - include the auto_path statements above - - activate tclreadline (and thus in tclshrc an event loop) - - To use them simply copy them into your home directory (or soft link them) - - cd $HOME - ln -s $RETROBASE/tools/tcl/.tclshrc . - ln -s $RETROBASE/tools/tcl/.wishrc . - -6. The build system ------------------------------------------------------- - - The generation of - - FPGA firmware (e.g. .bit files) - - test benches (e.g. simulator images) - is based on make flows. - - Two design tools are currently supported - - Xilinx Vivado - - Artix-7 based board (Basys3, Nexys4) - - see README_buildsystem_Vivado.txt - - Xilinx ISE - - Spartan-3 and Spartan-6 based boards (S3board, Nexys2, Nexys3) - - see README_buildsystem_ISE.txt - -7. Building test benches -------------------------------------------------- - - General instructions are in - - README_buildsystem_Vivado.txt (for Basys3, Nexys4) - - README_buildsystem_ISE.txt (for S3board, Nexys2, Nexys3) - - For available test benches see w11a_tb_guide.txt - -8. Building systems and configuring FPGAs --------------------------------- - - General instructions are in - - README_buildsystem_Vivado.txt (for Basys3, Nexys4) - - README_buildsystem_ISE.txt (for S3board, Nexys2, Nexys3) - -8d. Available systems ------------------------------------------------ - - Ready to build designs are organized in the directories - - $RETROBASE/rtl/sys_gen// - - with - w11a w11a system - tst_rlink rlink over serial link tester - tst_rlink_cuff rlink over FX2 interface tester - - and - basys3 b3: Digilent Basys3 board - nexys4 n4: Digilent Nexys4 board (cellular RAM version) - nexys3 n3: Digilent Nexys3 board - nexys2 n2: Digilent Nexys2 board (-1200 FPGA version) - s3board s3: Digilent S3board (-1000 FPGA version) - - To build the designs locally use - - cd $RETROBASE/rtl/sys_gen// - make sys__.bit - - with in most cases = and = 2 letter abriviation for - the board, e.g. n4 for nexys4. - -8e. Available bitkits with bit and log files ------------------------- - - Tarballs with ready to use bit files and all logfiles from the tool - chain can be downloaded from - http://www.retro11.de/data/oc_w11/bitkits/ - This area is organized in folders for different releases. The tarball - file names contain information about release, Xlinix tool, and design: - __.tgz - - - Vivado based designs: - These designs can be loaded with the Vivado hardware server into the FPGA. - - - ISE based designs: - - These designs can be loaded with config_wrapper into the FPGA. The - procedures for the supported boards are given below. - - Notes: - 1. XTWI_PATH and RETROBASE environment variables must be defined. - 2. config_wrapper bit2svf is only needed once to create the svf files. - 3. fx2load_wrapper is needed once after each board power on. - - a. for Digilent Nexys3 board (using Cypress FX2 USB controller) - - xtwi config_wrapper --board=nexys3 bit2svf .bit - fx2load_wrapper --board=nexys3 - xtwi config_wrapper --board=nexys3 jconfig .svf - - b. for Digilent Nexys2 board (using Cypress FX2 USB controller) - - xtwi config_wrapper --board=nexys2 bit2svf .bit - fx2load_wrapper --board=nexys2 - xtwi config_wrapper --board=nexys2 jconfig .svf - - c. for Digilent S3board (using ISE Impact) - - xtwi config_wrapper --board=s3board iconfig .bit - - -9. Generate Doxygen based source code view -------------------------------- - - Currently there is not much real documentation included in the source - files. The doxygen generated html output is nevertheless very useful - to browse the code. C++, Tcl and Vhdl source are covered by setup files - contained in the project files. - - To generate the html files - - cd $RETROBASE/tools/dox - export RETRODOXY - ./make_doxy - - If RETRODOXY is not defined '/tmp' is used. To view the docs use - - firefox $RETRODOXY/w11/cpp/html/index.html & - firefox $RETRODOXY/w11/tcl/html/index.html & - firefox $RETRODOXY/w11/vhd/html/index.html & diff --git a/doc/INSTALL_from_opencores.md b/doc/INSTALL_from_opencores.md new file mode 100644 index 00000000..9a0b62be --- /dev/null +++ b/doc/INSTALL_from_opencores.md @@ -0,0 +1,28 @@ +# Installl from legacy OpenCores svn repository + +The w11 project started on +[OpenCores](http://opencores.org) as project +[w11](http://opencores.org/project,w11). + +In October 2016 the repository was [moved from OpenCores to GitHub](https://wfjm.github.io/blogs/w11/2016-12-11-w11-moved-to-github.html). +The full revision history was kept and can be accessed from +[GitHub wfjm/w11](https://github.com/wfjm/w11). + +The OpenCores svn repository remains available and can also be used to +retrieve old revisions: + +- to download tagged verions (from major releases) list available svn tags + + svn ls http://opencores.org/ocsvn/w11/w11/tags + + and download one of them + + cd + svn co http://opencores.org/ocsvn/w11/w11/tags/ + +- to download specific svn revision (from minor releases) determine desired + svn revsion from list given on http://opencores.org/project,w11,overview + and download + + cd + svn co -r http://opencores.org/ocsvn/w11/w11/trunk diff --git a/doc/INSTALL_fx2_support.md b/doc/INSTALL_fx2_support.md new file mode 100644 index 00000000..62e1b3ce --- /dev/null +++ b/doc/INSTALL_fx2_support.md @@ -0,0 +1,77 @@ +# Install Cypress FX2 Support + +The Nexys2 and Nexys3 board feature a Cypress FX2 USB interface. It allows +to configure the FPGA and to transfer between FPGA and a PC. The retro +project uses a custom firmware in the FX2, this writeup describes the +installation of tools, environment setup and generation of the FX2 firmware. + +### Table of content + +- [System requirements](#user-content-sysreq) +- [Setup environment variables](#user-content-envvar) +- [Setup USB access](#user-content-usb-access) +- [Rebuild Cypress FX2 firmware](#user-content-fx2-firmware) + +### System requirements + +the download contains pre-build firmware images for the Cypress FX2 +USB Interface. Re-building them requires +- Small Device C Compiler -> package: `sdcc` `sdcc-ucsim` +- for FX2 firmware download and jtag programming over USB one needs + - fxload -> package: `fxload` + - urjtag -> package: `urjtag` for Ubuntu 12.04 and newer + see [INSTALL_urjtag.md](INSTALL_urjtag.md) for other distributions !! + +### Setup environment variables + +The default USB VID and PID is defined by two environment variables. +For internal lab use one can use + + export RETRO_FX2_VID=16c0 + export RETRO_FX2_PID=03ef + +> **Carefully read the disclaimer about usage of USB VID/PID numbers +> in the file [README_USB-VID-PID.md](README_USB-VID-PID.md). You'll be responsible for a +> misuse of the defaults provided with the project sources. +> Usage of this VID/PID in any commercial product is forbidden.** + +### Setup USB access + +For using the Cypress FX2 USB interface on Digilent Nexys2, Nexys3 and +Atlys boards `udev` rules must be setup to allow user level access to +these devices. A set of rules is provided under + + $RETROBASE/tools/fx2/sys + +Follow the 'README.txt' file in this directory. + +Notes: +- the provided udev rules use the VID/PID for **internal lab use** as + described above. If a different VID/PID is used the file must be modified. +- your user account must be in group `plugdev` (should be the default). + +### Rebuild Cypress FX2 firmware + +The download includes pre-build firmware images for the Cypress FX2 +USB interface used on the Digilent Nexys2, Nexys3 and Atlys Boards. +These firmware images are under + + $RETROBASE/tools/fx2/bin + +To re-build them, e.g. because a different USB VID/PID is to be used + + cd $RETROBASE/tools/fx2/src + make clean + make + make install + +Note: The default build assumes that sdcc with a version 3.x is installed. +In case sdcc 2.x is installed use + + make SDCC29=1 + +instead. See also tools/fx2/src/README.txt. + +Please read [README_USB_VID-PID.md](README_USB_VID-PID.md) carefully to +understand the usage of USB VID and PID. + diff --git a/doc/INSTALL_fx2_support.txt b/doc/INSTALL_fx2_support.txt deleted file mode 100644 index c47dbe82..00000000 --- a/doc/INSTALL_fx2_support.txt +++ /dev/null @@ -1,79 +0,0 @@ -# $Id: INSTALL_fx2_support.txt 654 2015-03-01 18:45:38Z mueller $ - -The Nexys2 and Nexys3 board feature a Cypress FX2 USB interface. It allows -to configure the FPGA and to transfer between FPGA and a PC. The retro -project uses a custom firmware in the FX2, this writeup describes the -installation of tools, environment setup and generation of the FX2 firmware. - - Table of content: - - 1. System requirements - 2. Setup environment variables - 3. Setup USB access - 4. Rebuild Cypress FX2 firmware - -1. System requirements ---------------------------------------------------- - - - the download contains pre-build firmware images for the Cypress FX2 - USB Interface. Re-building them requires - - Small Device C Compiler - -> package: sdcc sdcc-ucsim - - - for FX2 firmware download and jtag programming over USB one needs - - fxload - -> package: fxload - - urjtag - -> package: urjtag for Ubuntu 12.04 - -> see INSTALL_urjtag.txt for other distributions !! - -2. Setup environment variables --------------------------------------------- - - The default USB VID and PID is defined by two environment variables. - For internal lab use one can use - - export RETRO_FX2_VID=16c0 - export RETRO_FX2_PID=03ef - - !! Carefully read the disclaimer about usage of USB VID/PID numbers !! - !! in the file README_USB-VID-PID.txt. You'll be responsible for any !! - !! misuse of the defaults provided with the project sources. !! - !! Usage of this VID/PID in any commercial product is forbidden. !! - -3. Setup USB access ------------------------------------------------------- - - For using the Cypress FX2 USB interface on Digilent Nexys2, Nexys3 and - Atlys boards 'udev' rules must be setup to allow user level access to - these devices. A set of rules is provided under - - $RETROBASE/tools/fx2/sys - - Follow the 'README.txt' file in this directory. - - Notes: - - the provided udev rules use the VID/PID for 'internal lab use' as - described above. If other VID/PID used the file must be modified. - - your user account must be in group 'plugdev' (should be the default). - -4. Rebuild Cypress FX2 firmware ------------------------------------------- - - The download includes pre-build firmware images for the Cypress FX2 - USB interface used on the Digilent Nexys2, Nexys3 and Atlys Boards. - These firmware images are under - - $RETROBASE/tools/fx2/bin - - To re-build them, e.g. because a different USB VID/PID is to be used - - cd $RETROBASE/tools/fx2/src - make clean - make - make install - - Note: The default build assumes that sdcc with a version 3.x is installed. - In case sdcc 2.x is installed use - make SDCC29=1 - instead. See also tools/fx2/src/README.txt in the - - Please read README_USB_VID-PID.txt carefully to understand the usage - of USB VID and PID. - diff --git a/doc/INSTALL_ghdl.txt b/doc/INSTALL_ghdl.md similarity index 77% rename from doc/INSTALL_ghdl.txt rename to doc/INSTALL_ghdl.md index 3b01e506..3a17ae6f 100644 --- a/doc/INSTALL_ghdl.txt +++ b/doc/INSTALL_ghdl.md @@ -1,8 +1,6 @@ -# $Id: INSTALL_ghdl.txt 651 2015-02-26 21:32:15Z mueller $ +# Installation of ghdl -The w11 project uses the open source VHDL simulator - - ghdl +The w11 project uses the open source VHDL simulator **ghdl**. It used to be part of most distributions. Unfortunately the Debian maintainer for ghdl refused at some point to integrate ghdl into Debian Etch. Therefore @@ -15,40 +13,38 @@ ghdl, the currently maintained versions 12.04 LTS "Precise", 14.04 LTS "Trusty" and 14.10 "Utopic" unfortunately don't. To install ghdl on an up-to-date Debian or Ubuntu systems you have the -following options {as of early February 2015}: +following options _(as of early February 2015)_: - Ubuntu Precise and Trusty Thanks to Peter Gavin Ubuntu packages for GHDL are available from his PPA 'Personal Package Archives', see - https://launchpad.net/~pgavin/+archive/ghdl + https://launchpad.net/~pgavin/+archive/ghdl So to install ghdl under Ubuntu use - sudo add-apt-repository ppa:pgavin/ghdl - sudo apt-get update - sudo apt-get install ghdl + sudo add-apt-repository ppa:pgavin/ghdl + sudo apt-get update + sudo apt-get install ghdl - Debian Wheezy Thanks to Joris van Rantwijk Debian packages for GHDL are available from the web site - http://jorisvr.nl/ghdl_debian.html + http://jorisvr.nl/ghdl_debian.html There are also Ubuntu packages, but Joris focus is clearly on Debian. Only Debian and Ubuntu are actively used by the w11a developer. The situation for other Linux distributions is therefore just taken from the respective web -sites {status October 2013}: +sites _(status October 2013)_: -- Suse +- **Suse** For Suse 12.2 and 12.3 un-official ghdl packages are available, but they seem to be based on the long obsolete ghdl version 0.27. - -- Redhat/Fedora +- **Redhat/Fedora** For Fedora 18,19, and 20 packages are available based on ghdl 0.29 - -- Gentoo +- **Gentoo** Packages, marked 'unstable', are available based on ghdl 0.29 and 0.27 diff --git a/doc/INSTALL_urjtag.md b/doc/INSTALL_urjtag.md new file mode 100644 index 00000000..f52ed30e --- /dev/null +++ b/doc/INSTALL_urjtag.md @@ -0,0 +1,50 @@ +# Installation of urjtag + +The w11 project uses the open source JTAG Access software from the +SourceForge project +[urjtag](https://sourceforge.net/projects/urjtag/) +for configuring FPGA over the Cypress FX2 USB Interface available on +Digilent Nexys2, Nexys3 and Atlys boards. + +The most recent version works fine. This version is delivered with +Ubuntu 12.04 LTS and later Ubuntu versions. In this case simply install the +package `urjtag`. Try the command + + jtag + +it should print + + UrJTAG 0.10 #2007 + +and show a version number of `#2007` or higher. + +Old versions unfortunately have a string size limitation problem with can +lead to problems when used with Digilent S3BOARDS (or other cases with +multiple devices in the jtag chain). Therefore for + + Debian Squeeze and older + Ubuntu 11.10 (oneiric) and older + +or if the 'jtag' command prints something like + + UrJTAG 0.10 #1502 + UrJTAG 0.9 #1476 + +it is advisible to install the urjtag software from sources. + +Simlest is to install an up-to-date version directly from the SourceForge +svn repository, start at +https://sourceforge.net/p/urjtag/svn/HEAD/tree/trunk/ , do a +`svn co` for revision `2007` or later, build and install. + +Alternatively start with the `V0.10 (rev #1502)` tarball available from +https://sourceforge.net/projects/urjtag/files/ +and download + + urjtag-0.10.tar.gz (dated 2009-04-17) + +Change in file `src/cmd/parse.c` the line + + #define MAXINPUTLINE 100 /* Maximum input line length */ + +and replace `100` with `512`, build and install. diff --git a/doc/INSTALL_urjtag.txt b/doc/INSTALL_urjtag.txt deleted file mode 100644 index 442c0a6b..00000000 --- a/doc/INSTALL_urjtag.txt +++ /dev/null @@ -1,51 +0,0 @@ -# $Id: INSTALL_urjtag.txt 467 2013-01-02 19:49:05Z mueller $ - -The w11 project uses the open source JTAG Access software from the -SourceForge project - - urjtag - -for configuring FPGA over the Cypress FX2 USB Interface available on Digilent -Nexys2, Nexys3 and Atlys boards. - -The most recent version works fine. This version is delivered with -Ubuntu 12.04 LTS and later Ubuntu versions. In this case simply install the -package 'urjtag'. Try the command - - jtag - -it should print - - UrJTAG 0.10 #2007 - -and show a version number of '#2007' or higher. - -Old versions unfortunately have a string size limitation problem with can -lead to problems when used with Digilent S3BOARDS (or other cases with -multiple devices in the jtag chain). Therefore for - - Debian Squeeze and older - Ubuntu 11.10 (oneiric) and older - -or if the 'jtag' command prints something like - - UrJTAG 0.10 #1502 - UrJTAG 0.9 #1476 - -it is advisible to install the urjtag software from sources. - -Simlest is to install an up-to-date version directly from the SourceForge -svn repository, start at - http://sourceforge.net/scm/?type=svn&group_id=193266&source=navbar -do a 'svn co' for revision 2007 or later, build and install. - -Alternatively start with the V0.10 (rev #1502) tarball available from - http://sourceforge.net/projects/urjtag/files/?source=navbar -and download - urjtag-0.10.tar.gz (dated 2009-04-17) - -Change in file src/cmd/parse.c the line - - #define MAXINPUTLINE 100 /* Maximum input line length */ - -and replace '100' with '512', build and install. diff --git a/doc/README-w11a_V.60-w11a_V0.70.txt b/doc/README-w11a_V.60-w11a_V0.70.txt deleted file mode 100644 index 04c7b288..00000000 --- a/doc/README-w11a_V.60-w11a_V0.70.txt +++ /dev/null @@ -1,620 +0,0 @@ -$Id: README-w11a_V.60-w11a_V0.70.txt 695 2015-06-28 11:22:52Z mueller $ - -Release notes for w11a - - Table of content: - - 1. Documentation - 2. Change Log - -1. Documentation ------------------------------------------------------------- - - More detailed information on installation, build and test can be found - in the doc directory, specifically - - * README.txt: release notes - * README_known_issues.txt: known issues - * INSTALL.txt: installation and building test benches and systems - * FILES.txt: short description of the directory layout, what is where ? - * w11a_tb_guide.txt: running test benches - * w11a_os_guide.txt: booting operating systems - * w11a_known_issues.txt: known differences, limitations and issues - -2. Change Log ---------------------------------------------------------------- - -- w11a_V0.60 -> w11a_V0.70 cummulative summary of key changes - - Bugfix for DIV instruction (in w11a_V0.61, see ECO-026-div.txt) - - revised rbus protocol V4 (in w11a_V0.62, see README_Rlink_V4.txt) - - add basic Vivado support (in w11a_V0.64) - - add Nexys4 and Basys3 port of w11a (in w11a_V0.64) - - add RL11/RL02 disk support (in w11a_V0.64) - - add RH70+RP/RM disk support (in w11a_V0.65) - - add TM11/TY10 tape support (in w11a_V0.66) - - reference system now ISE 14.7, Vivado 2014.4; Ubuntu 14.04 64 bit, ghdl 0.31 - -- trunk (2015-06-21: svn rev 33(oc) 693(wfjm); tagged w11a_V0.70) +++++++++++ - - Preface - - resolved known issue V0.66-2: operation with multiple RP or RM disks - under 211bsd works now. Issue was caused by a faulty error check. - - resolved bug tracker issue 2015-06-06: the tm11 offline function works - now as expected. Issue was caused by de-referencing a null pointer. - - resolved bug tracker request 2015-06-05: the values returned as drive - serial number were interpreted by 211bsd standalone code as a signature - of SI drives, which made disk partitioning a bit cumbersome. Changed the - scheme used to generate drive serial numbers such that they never match - these 3rd party drive characteristics. The 211bsd installation on a - RM05 is documented with the 211bsd_tm oskit. - - the w11a designs grow larger, filling the FPGA's on Nexys2 and Nexys3 - to ~50% (n2) or 67% (n3). To reach timing closure without fine tuning - constraints the cpu clock had to be reduced to - sys_w11a_n2 now 52 MHz (was 54 MHz) - sys_w11a_n3 now 64 MHz (was 68 MHz) - - - w11a has now a complete set of mass storage peripherals. This is a good - reason of a major release, thus go for version V0.70. - - - there are many known issues, and in many cases only core functionality - used by operating systems has been implemented. The missing parts will - be implemented in the upcoming releases towards V0.80, also much more - intensive testing, especially with maindecs (aka xxdp) will be done. - - - Summary - - rhrp and tm11 bug fixes - - no major functionality added - - - New features - - - Changes - - renames - - tools/oskit/211bsd_tm/211bsd_tm_boot.* -> 211bsd_tm_rp06_boot.* - - functional changes - - rtl/ibus/ibdr_rhrp - modify sn register to avoid 211bsd issues - - tools/bin/create_disk - support RM80 disks - - tools/tcl/rutil/util.tcl - add dohook - - tools/oskit/*/*_boot.tcl - add preinithook and preboothook - - - Bug fixes - - rtl/ibus/ibdr_rhrp - set er1.rmr only when unit busy - - set cs2.pge only when controller busy - - tools/src/librw11 - - Rw11CntlTM11 - fix crash when offline function was executed - - - Known issues - - all issues: see README_known_issues.txt - - resolved issues: - - V0.66-2: operation with multiple RP/RM drives works now under 211bsd - -- trunk (2015-06-05: svn rev 31(oc) 687(wfjm); untagged w11a_V0.66) +++++++++ - - Preface - - - Since the previous release a full set of small, medium and large sized - disks (RK,RL,RP/RM) is available, covering all use cases. Still missing - was a tape system, which allows to install systems from distribution tapes - but is also very handy for data exchange. This release adds a TM11/TU10 - tape controller emulation. This is much simpler to implement than a - massbus based TU16 or TU78 controller. Because storage is emulated there - is neither a speed nor a capacity advantage of 1600 or 6250 bpi drives, - so for all practical purposes the simple 800 bpi TU10 drive emulation is - fully adequate. - The TM11/TU10 was tested under 211bsd with creating a tape distribution - kit and building a RP06 based system from such a tape. A 211bsd_tm - oskit is provided with a recipe to restore a RP06 from tape. - - - bug fixes - - the ti_rri event loop aborted under heavy load with three devices, seen - when RP disk, TM tape and DL11 run simultaneously. Was caused by a race - condition in attention handling and dispatching. - - the boot command failed when cpu was running and the unit not decoded - properly, so boots from units other then 0 failed. - - - Summary - - added TM11/TU10 tape support - - - New features - - new modules - - rtl/ibus/ibdr_rm11 - ibus controller for RM11 - - tools/bin - - file2tap - create a tap container from disk files - - tap2file - split a tap container into disk files - - tools/src/librw11 - - Rw11(Cntl|Unit)TM11 - Controller/Unit for TM11 - - Rw11UnitTape(|Base) - support for tape units - - Rw11VirtTape(|Tap) - virtual tapes (generic and tap containers) - - tools/tcl/rw11 - - tbench.tcl - support sub directories and return in tests - - new oskits - - tools/oskit/211bsd_tm - 2.11BSD tape distribution kit (for RP06) - - - Changes - - renames - - tools/tbench - the text benches were re-organized and - grouped now in sub directories: - cp for w11a control port - w11a for w11a CPU tests - rhrp for RHRP device tests - tm11 for TM11 device tests - - functional changes - - tools/bin/create_disk - add RM80 support - - - Bug fixes - - tools/src/librlink - - RlinkServer - fix race condition in attention handling - - tools/src/librw11 - - Rw11Cpu - stop cpu before load, proper unit handling - - - Known issues - - all issues: see README_known_issues.txt - - resolved issues: -- none -- - - new issues: - - V0.66-1: the TM11 controller transfers data byte wise (all disk do it - 16bit word wise) and allows for odd byte length transfers. Odd length - transfers are currently not supported and rejected as invalid command. - Odd byte length records aren't used by OS, if at all, so in practice - this limitation isn't relevant. - - V0.66-2: using two RP06 drives in parallel under 211bsd leads to a - hangup of the system after a short time. Currently only operation - of a single drive works reliably. - -- trunk (2015-05-14: svn rev 30(oc) 681(wfjm); untagged w11a_V0.65) +++++++++ - - Preface - - - With small RK05 or RL02 sized disks only quite reduced OS setups could - be booted, full featured systems were beyond reach. Now finally large - disks are available, with a RH70 + RP/RM disk controller emulation. It - supports up to four disks and allows now to run full featured 211bsd - or rsx-11mplus systems. - - - to track down issues with ibus devices a 'ibus monitor' was added, it can - record in the default setup up to 511 ibus transactions. An address filter - allows to select accesses of one device. The ibd_ibmon tcl package - contains the appropriate support scripts. - - - several cleanups - - factor out common blocks on sys_w11a_* systems: the core+rbus+cache - logic of single cpu systems now contained in pdp11_sys70, and the - human I/O for digilent boards now in pdp11_hio70. - - cpu start/stop logic cleanup: new command set with simple commands. - Add also a new suspend/resume mechanism, which allows to hold the cpu - without leaving the 'run state'. While suspended all timers are frozen. - Very helpful when debugging, will be the basis for a hardware break - point logic in a later release. - - xon/xoff consolidation: escaping now done in cdata2byte/byte2cdata in - FPGA and in RlinkPacketBufSnd/RlinkPacketBufRcv in backend. The extra - escaping level in serport_xonrx/serport_xontx isn't used anymore, the - special code in RlinkPortTerm has been removed. This allows to use - xon/xoff flow control also in simulation links via RlinkPortFifo. - - status check cleanup: it is very helpful to have a default status check - and an easy way to modify it cases where some error flags are expected - (e.g. on device polls). In the old logic status and data checks were - done via RlinkCommandExpect. The new logic reflects that status checks - are the normal case, and store the status check pattern in RlinkCommand. - The meaning of expect masks for status and data is inverted, now a '1' - means that the bit is checked (before it meant the bit is ignored). - The default status check pattern is still in RlinkContext, but will be - copied to RlinkCommand when the list is processed. RlinkCommandExpect - handles now only data checks. - - - and bug fixes - - rk11 cleanup: since the first days 211bsd autoconfig printed - rk ? csr 177400 vector 220 didn't interrupt - for boots from a RK11 it didn't have consequences, but when booted from - a RL,RP, or RM disk this prevents that the RK11 disks are configured. - Was caused by a missing interrupt after device reset. Now fixed. - - - Summary - - added RH70/RP/RM big disk support - - many cleanups - - - New features - - new directory trees for - - tools/asm-11/lib - definitions and macros for asm-11 - - new modules - - rtl/vlib/serport - - serport_master - serial port module, master side - - rtl/ibus/ibd_ibmon - ibus monitor - - rtl/ibus/ibdr_rhrp - ibus controller for RH70 plus RP/RM drives - - rtl/w11a/pdp11_sys70 - 11/70 system - single core +rbus,debug,cache - - rtl/w11a/pdp11_hio70 - hio led and dsp for sys70 - - tools/src/librw11 - - Rw11(Cntl|Unit)RHRP - Controller/Unit for RHRP - - tools/tbench - - test_rhrp_* - test tbench for RHRP - - new oskits - - tools/oskit/211bsd_rp - new oskit for 2.11BSD on RP06 - - tools/oskit/rsx11mp-30_rp - new oskit for RSX-11Mplus V3.0 on RP06 - - - Changes - - renames - - rtl/w11a/pdp11_sys70 -> pdp11_reg70 (_sys70 now different function) - - functional changes - - rtl/bplib/*/tb/tb_* - use serport_master instead of - serport_uart_rxtx, allow xon/xoff - - rtl/bplib/fx2rlink - - rlink_sp1c_fx2 - add rbd_rbmon (optional via generics) - - rtl/vlib/rlink/rlink_sp1c - add rbd_rbmon (optional via generics) - - rtl/ibus/ibd_kw11l - freeze timer when cpu suspended - - tools/bin/tbrun_tbwrri - add --fusp,--xon - - tools/bin/ti_w11 - rename -fu->-fc, add -f2,-fx; setup defaults - - tools/bin/librlink - - RlinkCommandList - add SetLastExpect() methods - - RlinkPort - add XonEnable() - - RlinkPortCuff - add noinit attribute - - RlinkPort(Fifo|Term) - add xon,noinit attributes - - tools/src/librw11 - - Rw11Cpu - add AddRbibr(), AddWbibr(), RAddrMap() - - tools/bin/librlinktpp - - RtclRlinkConnect - errcnt: add -increment - log: add -bare,-info.. - wtlam: allow tout=0 for attn cleanup - init: new command - exec: drop -estatdef - - RtclRlinkServer - get/set interface added - - tools/src/librwxxtpp - - RtclRw11Cntl - start: new command - - RtclRw11Cpu - cp: add -rbibr, wbibr, -rreg,...,-init - - cp: add -estat(err|nak|tout), drop estatdef - - rename amap->imap; add rmap - - - Bug fixes - - rtl/ibus - - ibdr_rk11 - interrupt after dreset and seek command start - - tools/src/librlink - - RlinkConnect - WaitAttn(): return 0. (not -1.) if poll - - RlinkServer - Stop(): fix race in (could hang) - - - Known issues - - all issues: see README_known_issues.txt - - resolved issues: -- none -- - - new issues: - - V0.65-1: ti_rri sometimes crashes in normal rundown (exit or ^D) when - a cuff: type rlink is active. One gets - terminate called after throwing an instance of 'Retro::Rexception' - what(): RlinkPortCuff::Cleanup(): driver thread failed to stop - doesn't affect normal operation, will be fixed in upcoming release. - - V0.65-2: some exotic RH70/RP/RM features and conditions not implemented - - last block transfered flag (in DS) - - CS2.BAI currently ignored and not handled - - read or write 'with header' gives currently ILF - All this isn't used by any OS, so in practice not relevant. - -- trunk (2015-03-01: svn rev 29(oc) 655(wfjm); untagged w11a_V0.64) +++++++++ - - - Preface - - The w11 project started on a Spartan-3 based Digilent S3board, and soon - moved on to a Nexys2 with much better connectivity. Next step was the - Spartan-6 based Nexys3. Now is time to continue with 7-Series FPGAs. - - When Vivado started in 2013 it was immediately clear that the architecture - is far superior to ISE. But tests with the first versions were sobering, - the w11a design either didn't compile at all, or produced faulty synthesis - results. In 2014 Vivado matured, and the current version 2014.4 works - fine with the w11a code base. - - The original Nexys4 board allowed to quickly port Nexys3 version because - both have the same memory chip. The newer Nexys4 DDR will be addressed - later. - - The BRAM capacity of FPGAs increased significantly over time. The low - cost Basys3 board with the second smallest Artix-7 (XC7A35T) has 200 KB - BRAM. That allows to implement a purely BRAM based w11a system with - 176 kB memory. Not enough for 2.11BSD, but for many other less demanding - OS available for a PDP11. - - The Nexyx4 and Basys3 have 16 LEDs. Not quite the 'blinking lights' - console of the classic 11/45 and 11/70, but enough to display the - well known OS typical light patterns the veterans remember so well. - - With a new design tool, a new FPGA generation, two new boards, and a - new interface for the rlink connection that some of the code and tools - base had to be re-organized. - - Last but not least: finally access to a bit bigger disks: RL11 support - - Many changes, some known issues, some rough edges may still lurke around - - - Summary - - added support for Vivado - - added support for Nexys4 and Basys3 boards - - added RL11 disk support - - lots of documentation updated - - - New features - - new directory trees for - - rtl/bplib/basys3 - support for Digilent Basys3 board - - rtl/bplib/nexys4 - support for Digilent Nexys4 board - - rtl/make_viv - make includes for Vivado - - new files - - tools/bin/xviv_ghdl_unisim - ghdl compile Vivado UNISIM & UNIMACRO libs - - new modules - - rtl/ibus/ibdr_rl11 - ibus controller for RL11 - - rtl/vlib/rlink/ioleds_sp1c - io activity leds for rlink+serport_1clk - - rtl/vlib/xlib - - s7_cmt_sfs_gsim - Series-7 CMT: simple vhdl model - - s7_cmt_sfs_unisim - Series-7 CMT: wrapper for UNISIM - - rtl/w11a - - pdp11_bram_memctl - simple BRAM based memctl - - pdp11_dspmux - mux for hio display - - pdp11_ledmux - mux for hio leds - - pdp11_statleds - status led generator - - tools/src/librw11/ - - Rw11*RL11 - classes for RL11 disk handling - - tools/src/librwxxtpp - - RtclRw11*RL11 - tcl iface for RL11 disk handling - - new systems - - rtl/sys_gen/tst_rlink - rlink tester - - basys3/sys_tst_rlink_b3 - for Basys3 - - nexys4/sys_tst_rlink_n4 - for Nexys4 - - rtl/sys_gen/tst_serloop - serport loop tester - - nexys4/sys_tst_serloop_n4 - for Nexys4 - - rtl/sys_gen/tst_snhumanio - human I/O tester - - basys3/sys_tst_snhumanio_b3 - for Basys3 - - nexys4/sys_tst_snhumanio_n4 - for Nexys4 - - rtl/sys_gen/w11a - w11a - - basys3/sys_w11a_b3 - small BRAM only (176 kB memory) - - nexys4/sys_w11a_n4 - with full 4 MB memory using cram - - new oskits - - tools/oskit/211bsd_rl - new oskit for 2.11BSD on RL02 - - tools/oskit/rt11-53_rl - new oskit for RT11 V5.3 on RL02 - - tools/oskit/xxdp_rl - new oskit for XXDP 22 and 25 on RL02 - - - Changes - - renames - - ensure that old ISE and new Vivado co-exists, ensure telling names - - rtl/make -> make_ise - - rtl/bplib/bpgen/sn_4x7segctl -> sn_7segctl - - tools/bin/isemsg_filter -> xise_msg_filter - - tools/bin/xilinx_ghdl_unisim -> xise_ghdl_unisim - - tools/bin/xilinx_ghdl_simprim -> xise_ghdl_simprim - - - retired files - - rtl/bplib/fx2lib - - fx2_2fifoctl_as - obsolete, wasn't actively used since long - - tools/bin - - set_ftdi_lat - obsolete, since kernel 2.6.32 the default is 1 ms - - xilinx_vhdl_chop - obsolete, since ISE 11 sources come chopped - - - functional changes - - $RETROBASE/Makefile - re-structured, many new targets - - rtl/bplib/bpgen - - sn_7segctl - handle also 8 digit displays - - sn_humanio - configurable SWI and DSP width - - sn_humanio_rbus - configurable SWI and DSP width - - rtl/vlib/serport - - serport_1clock - export fractional part of divider - - rtl/ibus - - ibdr_maxisys - add RL11 (ibdr_rl11) - - rtl/sys_gen/w11a/* - - sys_w11a_* - use new led and dsp control modules - - tools/src/librlink - - RlinkConnect - drop LogOpts, indivitual getter/setter - - RlinkPortTerm - support custom baud rates (5M,6M,10M,12M) - - tools/src/librtcltools - - RtclGetList - add '?' (key list) and '*' (kv list) - - RtclSetList - add '?' (key list) - - RlogFile - Open(): now with cout/cerr support - - tools/src/librlinktpp - - RtclRlinkConnect - drop config cmd, use get/set cmd - - RtclRlinkPort - drop config cmd, use get/set cmd - - tools/src/librw11 - - Rw11Rdma - PreExecCB() with nwdone and nwnext - - Rw11UnitDisk - add Nwrd2Nblk() - - tools/src/librwxxtpp - - RtclRw11CntlFactory - add RL11 support - - tools/bin - - xise_ghdl_unisim - handle also UNIMACRO lib - - vbomconv - handle Vivado flows too - - - Bug fixes - - tools/src/librw11 - - Rw11CntlRK11 - revise RdmaPostExecCB() logic - - - Known issues - - V0.64-7: ghdl simulated OS boots via ti_w11 (-n4 ect options) fail due to - a flow control issue (likely since V0.63). - - V0.64-6: IO delays still unconstraint in vivado. All critical IOs use - explicitly IOB flops, thus timing well defined. - - V0.64-5: w11a_tb_guide.txt covers only ISE based tests (see also V0.64-4). - - V0.64-4: No support for the Vivado simulator (xsim) yet. With ghdl only - functional simulations, post synthesis (_ssim) fails to compile. - - V0.64-3: Highest baud rate with basys3 and nexys4 is 10 MBaud. 10 MBaud - is not supported according to FTDI, but works. 12 MBaud in next release. - - V0.64-2: rlink throughput on basys3/nexys4 limited by serial port stack - round trip times. Will be overcome by libusb based custom driver. - - V0.64-1: The large default transfer size for disk accesses leads to bad - throughput in the DL11 emulation for low speed links, like the - 460kBaud the S3board is limited too. Will be overcome by a DL11 - controller with more buffering. - - V0.62-2: rlink v4 error recovery not yet implemented, will crash on error - - V0.62-1: Command lists aren't split to fit in retransmit buffer size - {last two issues not relevant for w11 backend over USB usage because - the backend produces proper command lists and the USB channel is - usually error free} - -- trunk (2015-01-04: svn rev 28(oc) 629(wfjm); untagged w11a_V0.63) +++++++++ - - - Summary - - the w11a rbus interface used so far a narrow dynamically adjusted - rbus->ibus window. Replaces with a 4k word window for whole IO page. - - utilize rlink protocol version 4 features in w11a backend - - use attn notifies to dispatch attn handlers - - use larger blocks (7*512 rather 1*512 bytes) for rdma transfers - - use labo and merge csr updates with last block transfer - - this combined reduces the number of round trips by a factor 2 to 3, - and in some cases the throughput accordingly. - - - Remarks on reference system - - still using tcl 8.5 (even though 8.6 is now default in Ub 14.04) - - don't use doxygen 1.8.8 and 1.8.9, it fails to generate vhdl docs - - - New features - - new modules - - tools/bin - - ghdl_assert_filter - filter to suppress startup warnings - - tbrun_tbw - wrapper for tbw based test benches - - tbrun_tbwrri - wrapper for ti_rri + tbw based test benches - - tools/src/librw11 - - Rw11Rdma - Rdma engine base class - - Rw11RdmaDisk - Rdma engine for disk emulation - - - Changes - - rtl/vlib/rlink - - rlink_core - use 4th stat bit to signal rbus timeout - - rtl/vlib/rbus - - rbd_rbmon - reorganized, supports now 16 bit addresses - - rtl/w11a - - pdp11_core_rbus - use full size 4k word ibus window - - tools/bin/tbw - add -fifo and -verbose options - - tools/src/librtools - - Rexception - add ctor from RerrMsg - - tools/src/librlink - - RlinkCommandExpect - rblk/wblk done counts now expectable - - RlinkConnect - cleanups and minor enhancements - - RlinkServer - use attn notifies to dispatch handlers - - tools/src/librw11 - - Rw11CntlRK11 - re-organize, use now Rw11RdmaDisk - - Rw11Cpu - add ibus address map - - tools/src/librwxxtpp - - RtclRw11CntlRK11 - add get/set for ChunkSize - - RtclRw11Cpu - add amap sub-command for ibus map access - - - Resolved known issues from V0.62 - - the rbus monitor (rbd_rbmon) has been updated to handle 16 bit addresses - - - Known issues - - (V0.62): rlink v4 error recovery not yet implemented, will crash on error - - (V0.62): command lists aren't split to fit in retransmit buffer size - {both issues not relevant for w11 backend over USB usage because the - backend produces proper command lists and the USB channel is error free} - -- trunk (2014-12-20: svn rev 27(oc) 614(wfjm); untagged w11a_V0.62) +++++++++ - - - Summary - - migrate to rlink protocol version 4 - - Goals for rlink v4 - - 16 bit addresses (instead of 8 bit) - - more robust encoding, support for error recovery at transport level - - add features to reduce round trips - - improved attention handling - - new 'list abort' command - - For further details see README_Rlink_V4.txt - - use own C++ based tcl shell tclshcpp instead of tclsh - - Notes: - 1. rlink protocol, core, and backend are updated in this release - 2. error recovery in backend not yet implemented - 3. the designs using rlink are still essentially unchanged - 4. the new rlink v4 features will be exploited in upcoming releases - - - New reference system - The development and test system was upgraded from Kubuntu 12.04 to 14.04. - The version of several key tools and libraries changed: - linux kernel 3.13.0 (was 3.2.0) - gcc/g++ 4.8.2 (was 4.6.3) - boost 1.54 (was 1.46.1) - libusb 1.0.17 (was 1.0.9) - perl 5.18.2 (was 5.14.2) - tcl 8.5.15 (was 8.5.11) - sdcc 3.3.0 (was 2.9.0) - doxygen 1.8.7 {installed from sources; Ub 14.04 has 1.8.6} - - Notes: - 1. still using tcl 8.5 (even though 8.6 is now default in Ub 14.04) - 2. sdcc 3.x is not source compatible with sdcc 2.9. The Makefile - allows to use both, see tools/fx2/src/README.txt . - 3. don't use doxygen 1.8.8, it fails to generate vhdl docs - - - New features - - new environment variables TCLLIB and TCLLIBNAME. TCLLIBNAME must be - defined, and hold the library name matching the Tcl version already - specified with TCLINC. - - new modules - - rtl/vlib/comlib/crc16 - 16 bit crc generator (replaces crc8) - - tools/src/tclshcpp/* - new tclshcpp shell - - - Changes - - rtl/vlib/comlib - - byte2cdata,cdata2byte - re-write, commas now 2 byte sequences - - rtl/vlib/rlink - - rlink_core - re-write for rlink v4 - - rtl/*/* - use new rlink v4 iface and 4 bit STAT - - rtl/vlib/rbus/rbd* - new addresses in 16 bit rlink space - - rtl/vlib/simlib/simlib - add simfifo_*, wait_*, writetrace - - tools/bin/ - - fx2load_wrapper - use _ic instead of _as as default firmware - - ti_rri - use tclshcpp (C++ based) rather tclsh - - tools/fx2/bin/*.ihx - recompiled with sdcc 3.3.0 + bugfixes - - tools/fx2/src/Makefile - support sdcc 3.3.0 - - tools/src/ - - */*.cpp - adopt for rlink v4; use nullptr - - librlink/RlinkCrc16 - 16 crc, replaces RlinkCrc8 - - librlink/RlinkConnect - many changes for rlink v4 - - librlink/RlinkPacketBuf* - re-write for for rlink v4 - - tools/tcl/*/*.tcl - adopt for rlink v4 - - renames: - - tools/bin/telnet_starter -> tools/bin/console_starter - - - Bug fixes - - tools/fx2/src - - dscr_gen.A51 - correct string 0 descriptor - - lib/syncdelay.h - handle triple nop now properly - - - Known issues - - rlink v4 error recovery not yet implemented, will crash on error - - command lists aren't split to fit in retransmit buffer size - {both issues not relevant for w11 backend over USB usage because the - backend produces proper command lists and the USB channel is error free} - - the rbus monitor (rbd_rbmon) not yet handling 16 bit addresses and - therefore of limited use - -- trunk (2014-08-08: svn rev 25(oc) 579(wfjm); tagged w11a_V0.61) +++++++++++ - - - Summary - - The div instruction gave wrong results in some corner cases when either - divisor or quotient were the largest negative integer (100000 or -32768). - This is corrected now, for details see ECO-026-div.txt - - some minor updates and fixes to support scripts - - xtwi usage and XTWI_PATH setup explained in INSTALL.txt - - - New features - - the Makefile's for in all rtl building block directories allow now to - configure the target board for a test synthesis via the XTW_BOARD - environment variable or XTW_BOARD= make option. - - - Changes - - tools/bin/asm-11 - add call and return opcodes - - tools/bin/create_disk - add RM02,RM05,RP04,RP07 support - - tools/bin/tbw - use xtwi to start ISim models - - tools/bin/ticonv_pdpcp - add --tout and --cmax; support .sdef - - tools/dox/*.Doxyfile - use now doxygen 1.8.7 - - tools/src/librw11 - - Rw11CntlRK11 - add statistics - - - Bug fixes - - rtl/w11a - div bug ECO-026 - - pdp11_munit - port changes; fix divide logic - - pdp11_sequencer - s_opg_div_sr: check for late div_quit - - pdp11_dpath - port changes for pdp11_munit - - tools/bin/create_disk - repair --boot option (was inaccessible) - - tools/bin/ti_w11 - split args now into ti_w11 opts and cmds - - tools/src/librwxxtpp - - RtclRw11Cpu - redo estatdef logic; avoid LastExpect() - - tools/dox/make_doxy - create directories, fix 'to view use' text - -- w11a_V0.6 (2014-06-06) +++++++++++++++++++++++++++++++++++++++++++++++++++++ - - cummulative summary of key changes from w11a_V0.5 to w11a_V0.6 - - revised ibus protocol V2 (in w11a_V0.51) - - revised rbus protocol V3 (in w11a_V0.52) - - backend server rewritten in C++ and Tcl (in w11a_V0.53 and w11a_V0.562) - - add Nexys3 port of w11a (in w11a_V0.54) - - add Cypress FX2 support (in w11a_V0.56 and w11a_V0.57) - - added LP11,PC11 support (in w11a_V0.58) - - reference system now ISE 14.7 and Ubuntu 12.04 64 bit, ghdl 0.31 - - many code cleanups; use numeric_std - - many documentation improvements - - development status upgraded to beta (from alpha) - - for details see README-w11a_V.50-w11a_V0.60.txt - -- w11a_V0.5 (2010-07-23) +++++++++++++++++++++++++++++++++++++++++++++++++++++ - - Initial release with - - w11a CPU core - - basic set of peripherals: kw11l, dl11, lp11, pc11, rk11/rk05 - - just for fun: iist (not fully implemented and tested yet) - - two complete system configurations with - - for a Digilent S3board rtl/sys_gen/w11a/s3board/sys_w11a_s3 - - for a Digilent Nexys2 rtl/sys_gen/w11a/nexys2/sys_w11a_n2 diff --git a/doc/README.txt b/doc/README.txt deleted file mode 100644 index 34c687be..00000000 --- a/doc/README.txt +++ /dev/null @@ -1,643 +0,0 @@ -$Id: README.txt 811 2016-10-03 07:24:02Z mueller $ - -Release notes for w11a - - Table of content: - - 1. Documentation - 2. Change Log - -1. Documentation ------------------------------------------------------------- - - More detailed information on installation, build and test can be found - in the doc directory, specifically - - * README.txt: release notes - * README_known_issues.txt: known issues - * INSTALL.txt: installation and building test benches and systems - * FILES.txt: short description of the directory layout, what is where ? - * w11a_tb_guide.txt: running test benches - * w11a_os_guide.txt: booting operating systems - * w11a_known_issues.txt: known differences, limitations and issues - -2. Change Log ---------------------------------------------------------------- - -- trunk (2016-10-02: svn rev 37(oc) 811(wfjm); untagged w11a_V0.74) +++++++++ - - Preface - - the current version of the memory controller for the micron mt45w8mw16b - 'cellular ram' used on nexys2, nexys3, and nexys4 uses the asynchronous - access mode. The device supports a 'page mode' to speed up read access to - subsequent addresses. Even though prepared in the controller logic this - feature was simply forgotten. This is now properly implemented and - results in a bit faster cache line load times. The overall performance - of a w11a design is measurably, but marginally better. - - many unit tests still used a ISE environment. All board independent - tests were converted now to a vivado environment, only tests which - really depend a FPGA not supported by vivado stay with ISE. - - a total of 82 unit or system tests are currently available. Many of them - can be executed by different simulation engines, ghdl or the ISE/vivado - build-in simulators, and for different stages of the implementation flow, - from initial behavioral simulation over post-synthesis functional to final - post-routing timing simulation. This results in a large number of possible - tests. All test benches are all self-checking, but the execution of them - was so far not sufficiently automatized. - This was addressed with 'tbrun', a test bench driver, which obtains a - list of all available test benches from configuration files, selects - a subset given by selection criteria, and executes them. It can handle - the parallel execution of tests so multi-core systems can be very - easily exploited. Running all tests is now a single shell command. - - a new tool 'tbfilt' simplifies the logic of self-checking test benches - and can also be used as a tool to analyze the full log files produced - by the test benches - - several test benches have been added to this release, most notably the - memory tester sys_tst_sram_* which was originally developed to verify - the s3board SRAM controller and later ported to verify the nexys* CRAM - controller. - - the system test benches with SRAM and CRAM now include the PCB trace - delay between FPGA and memory chip. The new entity simbididly models a - bi-directional bus delay. - - so far test benches ended by stopping the clock, all processes were - written such that they enter a permanent wait, which causes the simulation - to stop. Worked for fine behavioral simulations, but fails when Xilinx - MMCMs are involved in post-synthesis simulations. The UNISIM models - apparently have timed waits. The test benches were modified to stop via a - report with severity failure, the test environment detects this specific - assertion/report failure and accepts it as successful termination of - the simulation. - - the configuration of the board switches in system test benches was done - in a sub-optimal way which could lead to startup problems. tbrun_tbwrri - uses now a different mechanism which ensures that all board and test - bench configuration is done in the first ns of the simulation and has - thus completed well before all other activities. - - finally a caveat: post-synthesis simulations work fine with ISE, but - currently not with vivado, even in case of almost identical designs, - like sys_tst_rlink_n3 vs sys_tst_rlink_n4. Is under investigation. - - - Summary - - upgraded CRAM controller, now with 'page mode' support - - new test bench driver tbrun, give automatized test bench execution - - - New features - - new modules - - rtl/bplib/issi/tb/* - added unit test for is61lv25616al model - - rtl/bplib/micron/tb/* - added unit test for mt45w8mw16b model - - rtl/sys_gen/tst_serloop - add serloop2 (2 clock) designs for n3,n4 - - nexys3/sys_tst_serloop2_n3.vhd - - nexys4/sys_tst_serloop2_n4.vhd - - rtl/sys_gen/tst_sram - add sram test design for - - nexys2/* - - nexys3/* - - nexys4/* - - s3board/* - - rtl/vlib/genlib/tb - - clkdivce_tb.vhd - copy for tb usage of clkdivce - - rtl/vlib/rlink/tb - - rlink_tba.vhd - rlink test bench adapter - - tb_rlink_tba.vhd - test bench for rbus devices - - tbd_tba_ttcombo.vhd - tba tester for ttcombo - - rtl/vlib/simlib - - simbididly.vhd - bi-di bus delay model - - rtl/vlib/xlib - - gsr_pulse.vhd - pulse GSR at startup - - gsr_pulse_dummy.vhd - no-action dummy (for bsim models) - - rtl/w11a/tb - - tb_rlink_tba_pdp11core.vhd - tba tester for w11a - - - new files - - doc/man/man1 - added tbrun,tbfilt man pages - - */tbrun.yml - test bench descriptors for tbrun - - rtl/sys_gen/w11a/tb - - tb_w11a_mem70*.dat - stim files for additional tests - - rtl/w11a/tb - - tb_pdp11core_ubmap.dat - stim files for additional test - - tools/bin - - njobihtm - determine #jobs - - tbfilt - test bench output filter - - tbrun - test bench driver - - ticonv_rri - converts old 'mode rri' for ti_rri - - tools/tcl/tst_sram/*.tcl - support for sys_tst_sram - - - Changes - - rtl/bplib - - arty/tb/tb_arty.vhd - add gsr_pulse (provisional....) - - */tb/tb_*.vhd - tbcore_rlink without CLK_STOP now - - fx2lib/tb/fx2_2fifo_core.vhd - proc_ifclk: remove clock stop - - nexys2/tb/tb_nexys2_core.vhd - use simbididly - - nexys3/tb/tb_nexys3_core.vhd - use simbididly - - nexys4/tb/tb_nexys4_cram.vhd - use simbididly - - nxcramlib - - nx_cram_memctl_as.vhd - add page mode support - - nxcramlib.vhd - add cram_*delay functions - - s3board - - s3_sram_memctl.vhd - drop "KEEP" for data (better for dbg) - - tb/tb_s3board_core.vhd - use simbididly - - rtl/make_ise - - generic_ghdl.mk - ghdl_clean: remove also gcov files - - rtl/make_viv - - generic_ghdl.mk - ghdl_clean: remove also gcov files - - generic_vivado.mk - viv_clean: rm only vivado logs - - generic_xsim.mk - xsim work dir now xsim.. - - rtl/sys_gen/tst_serloop - - */tb/tb_tst_serloop*.vhd - remove CLK_STOP logic - - tb/tb_tst_serloop.vhd - remove CLK_STOP logic - - rtl/sys_gen/w11a/nexys* - - sys_conf.vhd - use cram_*delay functions - - rtl/vlib/rlink - - rlink_core.vhd - remove 'assert false' from report stmts - - tb/tb_rlink.vhd - use clkdivce_tb - - tbcore/tbcore_rlink.vhd - conf: add .wait, CONF_DONE; drop CLK_STOP - - rtl/vlib/simlib - - simbus.vhd - rename SB_CLKSTOP > SB_SIMSTOP - - simclk.vhd - CLK_STOP now optional port - - rtl/vlib/xlib - - */s*_cmt_sfs_*.vhd - remove 'assert false' from report stmts - - tools/bin - - tbrun_tbwrri - add --r(l|b)mon,(b|s)wait; configure - now via _conf={...} - - tbw - use {} as delimiter for immediate mode - - vbomconv - add VBOMCONV_GHDL_OPTS and .._GHDL_GCOV - - xise_ghdl_* - add ghdlopts as 1st option; def is -O2 - - - removed files - - tools/bin/ghdl_assert_filter - obsolete (use tbfilt now) - - renames - - rtl/make_viv/viv_*.tcl -> tools/vivado - separate make and tools - - - Bug fixes - - tools/bin - - tbw - xsim: append -R to ARGV (was prepended...) - - xtwi - add ":." to PATH even under BARE_PATH - - - Known issues - - all issues: see README_known_issues.txt - - no resolved or new issues in this release - -- trunk (2016-06-26: svn rev 36(oc) 779(wfjm); untagged w11a_V0.73) +++++++++ - - Preface - - the 'basic vivado support' added with V0.64 was a minimal effort port of - the code base used under ISE, leading to sub-optimal results under vivado. - - the FSM inference under vivado is quirky and has several issues. The - most essential one prevented re-coding with 'one_hot' encoding, which - lead to high logic depth and low clock rates. Proper work-arounds were - applied to almost all FSMs, now vivado infers all (but one) properly - and re-codes them as 'one_hot'. That is especially important for the - pdp11_sequencer, which has 113 states. The sys_w11a_n4 system can now - run with up to 90 MHz (was 75-80 MHz before). - - due to a remaining synthesis issue the dmscnt and dmcmon debug units - are currently disabled for Artix based systems (see issue V0.73-3). - - memory inference is now used for all distributed and block rams under - vivado. The memory generators in memlib are still used under ISE - Note: they were initially setup to work around ISE synthesis issues. - - vivado synthesis and implementation use now 'explore' type flows for - optimal timing performance. - - the two clock dram based fifo was re-written (as fifo_2c_dram2) to allow - proper usage of vivado constraints (e.g. scoped xdc). - - - vivado is now the prime platform for all further development - - the component test benches run now by default under Vivado with an - Artix-7 as default target. The makefiles for ISE with a Spartan-6 target - are available as 'Makefile.ise' and via the 'makeise' command. - - a message filter (xviv_msg_filter) has been developed which lists only - the unexpected message of a synthesis or implementation run. Filter - rule sets (.vmfset files) are available for all designs. - - full support for the vivado simuator 'xsim' has been added, there are - make targets to build a behavioral simulation as well as post-synthesis, - post-optimize, and post-routing functional and timing models. All these - models are now created in separate sub-directories and can now co-exist. - However see issues V.073-1 and 0.73-2 for severe caveats on xsim. - - vivado write_vhdl generates code which violates a vhdl language rule. - Attributes of port signals are declared in the wrong place. xsim and - other simulators accept this, but ghdl doesn't. As a work-around the - generated code is cleaned up by a filter (see xviv_sim_vhdl_cleanup). - - - additional rlink devices - - the XADC block, available on all 7Series FPGAs, is now accessible via - rlink on all Arty, Basys3 and Nexys4 designs. Especially useful on the - Arty board because on this board also the currents are monitored. - - the USR_ACCESS register, available on all 7Series FPGAs, is now readable - via rlink on all Arty, Basys3 and Nexys4 designs. The vivado build flow - initializes this register with the build timestamp. This allows to - verify the build time of a design at run time. - - - the cache used by the w11a (pdp11_cache) was initialy developed with the - tight block ram resources of the early Spartan-3 systems in mind. It had - 8 kByte and used 5 BRAMs of size 18 kBit. With very little changes the - implenenation is now parametrized, and can generate also 16,32, 64 and - even 128 kByte caches which also use the 36 kBit BRAMs on the Artix. - There is a trade-off between cache sizes and clock rate due to routing - delays to the BRAM blocks. The w11a on the nexys4 runs with 16 kByte - cache and 90 MHz clock or with 64 kByte cache and 80 MHz. For practical - work loads, like a kernel compile, the 64 kByte configuration is better - and thus the default. - - - resolved known issue V0.64-7: was caused by a combination of issues - and is now resolved by a combination of measures: add portsel logic for - arty tb, proper portsel setup, configurable timeout, and finally proper - timeout setting. - - resolved known issue V0.64-3: So far the arty, basys3 and nexys4 serial - port, based on a FTDI FT2232, was often operated at 10 MBaud. This rate - is in fact not supported by FTDI, the chip will use 8 instead of 10 MBaud. - Due to auto-bauding, which simly adapts to the actual baud rate, this went - undetected for some time. Now all designs use a serport block clocked with - 120 MHz and can be operated with 12 MBaud. - - - Summary - - new reference system: switched to Vivado 2016.2 (from 2015.4) - - code base cleaned-up for vivado, fsm now inferred - - xsim support complete (but many issues to be resolved yet) - - added configurable w11a cache - - removed some never documented and now strategically obsolete designs: - - sys_tst_fx2loop (for nexys2 and nexys3) - - sys_tst_rlink_cuff_ic3 (a three channel variant of the fx2 interface) - - - New features - - new modules - - rtl/vlib - - generic_clk_100mhz.xdc - generic 100 MHz on CLK constraint (for tbs) - - rtl/vlib/cdclib - new directory for clock domain crossing - - cdc_pulse.vhd - cdc for a pulse (moved in from genlib) - - cdc_signal_s1.vhd - cdc for a signal, 2 stage - - cdc_vector_s0.vhd - cdc for a vector, 1 stage - - rtl/vlib/memlib - - fifo_2c_dram2.vhd - re-write of fifo_2c_dram to allow - proper usage of vivado constraints - - rtl/vlib/rbus - - rb_sres_or_6.vhd - rbus result or, 6 input - - rbd_usracc.vhd - return usr_access register - - rtl/vlib/rlink - - rlink_sp2c.vhd - rlink_core8 + serport_2clock2 combo - - rtl/vlib/serport - - serport_2clock2.vhd - like serport_2clock, use fifo_2c_dram2 - - rtl/vlib/xlib - - usr_access_unisim.vhd - Wrapper for USR_ACCESS* entities - - new files - - tools/bin - - xise_msg_summary - list all filtered ISE messages - - xviv_msg_filter - message filter for vivado - - xviv_msg_summary - list all filtered vivado messages - - xviv_sim_vhdl_cleanup - cleanup vivado generated vhdl for ghdl - - makeise - wrapper for make -f Makefile.ise - - tools/tcl/rbtest - - test_flow.tcl - test back pressure and flow control - - - Changes - - rtl/bplib/*/*_pins.xdc - add BITSTREAM.CONFIG.USR_ACCESS setup - - rtl/bplib/*/tb/tb_*.vbom - use -UUT attribute - - rtl/sys_gen/*/*/tb/tb_*.vbom - use -UUT attribute - - rtl/make_ise - - generic_ghdl.mk - use ghdl.?sim as workdir for ghdl - - generic_xflow.mk - use .imfset for ISE message rules - - rtl/make_viv - - generic_ghdl.mk - use ghdl.?sim as workdir for ghdl - - generic_vivado.mk - add [sorep]sim.v and %.vivado targets - - vmfset support, use xviv_sim_vhdl_cleanup - - generic_xsim.mk - [rep]sim models; use xsim.?sim as workdir - - viv_tools_build.tcl - use explore flows; prj,opt,pla modes - - viv_tools_config.tcl - add USR_ACCESS readback - - viv_tools_model.tcl - add [sor]sim_vhdl [sorepd]sim_veri modes - - rtl/sys_gen/*/* (all rlink based designs) - - sys_*.vhd - define rlink SYSID - - rtl/sys_gen/*/* (all rlink and 7series based designs) - - sys_*.vhd - add rbd_usracc, use serport_2clock2 - - sys_conf.vhd - use PLL for clkser_gentype - - rtl/sys_gen/w11a/* - - sys_conf.vhd - add sys_conf_cache_twidth - - rtl/sys_gen/tst_serloop/nexys4 - - sys_tst_serloop1_n4.vhd - clock now from cmt and configurable - - rtl/sys_gen/tst_serloop/tb - - tb_tst_serloop.vhd - use serport_(uart_rxtx|xontx)_tb - - rtl/vlib/*/tb/tb_*.vbom - use -UUT attribute - - rtl/vlib/*/tb/tbd_*.vbom - use generic_clk_100mhz.xdc - - rtl/vlib/comlib/comlib.vhd - leave return type unconstraint - - rtl/vlib/simlib/simlib.vhd - add writetimens() - - rtl/w11a - - pdp11_bram_memctl.vhd - use memory inference now - - pdp11_cache.vhd - now configurable size (8,16,32,64,128 kB) - - pdp11_sequencer.vhd - proc_snum conditional (vivado fsm fix) - - rtl/*/*.vbom - use memory inference for vivado - - rtl/*/*.vhd - workarounds and fixes to many FSMs - - tools/bin - - tbrun_tbw - use _bsim.log for behavioral sim log - - tbrun_tbwrri - use _bsim.log for behavioral sim log - use 120 sec timeout for simulation - - tbw - add '-norun', -run now default - - ti_rri - add --tout option - use 120 sec timeout for simulation - - vbomconv - add file properties (-UUT,-SCOPE_REF) - full xsim support now in -vsim_prj - - tools/src/librlink - - RlinkConnect - add USR_ACCESS register support - - tools/src/librlinktpp - - RtclRlinkConnect - add USR_ACCESS, timeout access - - tools/tcl/rbtest - - test_data.tcl - add dinc register tests - - tools/tcl/rlink - - util.tcl - add USR_ACCESS register support - - - removed designs - - rtl/sys_gen/tst_fx2loop/nexys*/*/sys_tst_fx2loop_*_n* - - rtl/sys_gen/tst_rlink_cuff/nexys2/ic3/sys_tst_rlink_cuff_ic3_n2 - - renames - - *.mfset -> *.imfset - to be complementary to new .vmfset - - Makefile -> Makefile.ise - old ISE makefiles in component areas - - - Bug fixes - - rtl/bplib/arty/tb - - tb_arty.vhd: - add portsel logic - - rtl/bplib/sysmon - - sysmon_rbus_core.vhd - use s_init (and not s_idle) after RESET - - rtl/vlib/xlib - - s7_cmt_sfs_*.vhd - correct mmcm range check boundaries - - tools/bin - - ti_w11: - proper portsel oob for -fx - - tbrun_tbwrri: - proper portsel oob for -hxon - - - Known issues - - all issues: see README_known_issues.txt - - resolved issues: - - V0.72-1: since vivado 2016.1 xelab builds models which use DPI in a - mixed vhdl-verilog language environment. - - V0.72-2: now full support to build behavioral as well as functional and - timing simulations with xsim. See V.073-1 and 0.73-2 for caveats. - - V0.64-7: flow control issues with simulation models resolved - - V0.64-3: basys3, nexys4 and arty designs support now 12 MBaud. - - - new issues: - - V0.73-1: as of vivado 2016.2 xelab shows sometimes extremely long build - times, especially for generated post-synthesis vhdl models. But also - building a behavioral simulation for a w11a design can take 25 min. - Even though post-synthesis or post-routing models are now generated - in verilog working with xsim is cumbersome and time consuming. - - V0.73-2: Many post-synthesis functional and especially post-routing - timing simulations currently fail due to startup and initialization - problems. Cause is MMCM/PLL startup, which is not properly reflected - in the test bench. Will be resolved in an upcoming release. - - V0.73-3: The 'state number generator' code in pdp11_sequencer causes - in vivado 2016.1 (and .2) that the main FSM isn't re-coded anymore, - which has high impact on achievable clock rate. The two optional - debug units depending on the state number, dmscnt and dmcmon, are - therefore currently deactivated in all Artix based systems (but are - available on all Spartan based systems). - -- trunk (2016-03-19: svn rev 35(oc) 746(wfjm); untagged w11a_V0.72) +++++++++ - - Preface - - The new low-cost Digilent Arty board is a very attractive platform. - The DDR3 memory will take some time to integrate, in this release thus - only designs using the BRAMs. - - added support for the Vivado simulator. Simple test benches work fine. - Rlink based test benches don't work due to a bug in Vivado 2015.4. - - A rather esoteric CPU bug was fixed in release V0.71 but forgotten to - mention in the README. See ECO-027-trap_mmu.txt for details. - - - Summary - - added Arty support. The w11a design uses BRAMs as memory, like the - Basys3 version. This gives 176 KByte memory, not enough for 2.11BSD, - but for many other less demanding OS available for a PDP11. - - added support for SYSMON/XADC (see README_xadc.txt) - - Vivado flow is now default for test benches of components and all Artix - based systems. If applicable an ISE flow is available under Makefile.ise - (resolves known issues V0.64-4 and V0.64-5). - - re-factored tbcore_rlink to support DPI and VHPI - - Vivado supports with DPI (from SystemVerilog) a mechanism to call - external C code. The rlink test bench code so far relies on VHPI, which - is supported by ghdl, but not by ISE ISim or Vivado xsim. The code was - restructured and can use now DPI or VHPI to support both ghdl and - Vivado. Unfortunately has Vivado 2015.4 a bug, DPI doesn't work in a - mixed vhdl-verilog language environment (see Known issues), so the - code base is there, but utilization will habe to wait. - - Vivado synthesis by default keeps hierarchy. This leads to doubly defined - modules if a component is used in both test bench and unit under test. - To avoid this copies of s7_cmt_sfs and some serport_* modules were - created and are now used in the test benches. - - - New features - - new directory trees for - - rtl/bplib/arty - board support files for arty - - rtl/bplib/sysmon - driver + rbus iface for SYSMON/XADC - - rtl/vlib/rlink/tbcore - new location for rlink tb iface code - - tools/tcl/rbsysmon - sysmon/xadc support - - new modules - - rtl/bplib/bpgen - - rgbdrv_* - driver + rbus iface for 3 color RGBLED - - rtl/vlib/rlink/tbcore - - rlink_cext_iface_dpi.sv - DPI based cext iface - - rlink_cext_iface_vhpi.vhd - VHPI based cext iface - - rlink_cext_dpi.c - dpi to vhpi adapter - - rtl/vlib/serport/tb - - serport_uart_*_tb - added copies for tb usage - - rtl/vlib/xlib/tb - - s7_cmt_sfs_tb - added copy for tb usage - - - new files - - doc/man/man1 - - tbrun_tbw.1 - man file for tbrun_tbw - - tbrun_tbwrri.1 - man file for tbrun_tbwrri - - new systems - - rtl/sys_gen/tst_rlink - rlink tester - - arty/sys_tst_rlink_arty - for Arty - - rtl/sys_gen/w11a - w11a - - arty_bram/sys_w11a_br_arty - for Arty (BRAM only, 176 MByte) - - - Changes - - */.cvsignore - all ignore files re-organized - - */tb/Makefile - Vivado now default, keep Makefile.ise - - rtl/bplib/*/tb/tb_*.vhd - use s7_cmt_sfs_tb and serport_master_tb - - rtl/vlib/comlib - - comlib.vhd - add work-around for vivado 2015.4 issue - - rtl/vlib/rbus - - rb_sres_or_mon - supports 6 inputs now - - rtl/vlib/serport - - serport_master - moved to tb, _tb appended to name - - rtl/vlib/rlink/tbcore - - tbcore_rlink - re-structured to use rlink_cext_iface - - rtl/sys_gen/... - - sys_tst_rlink_b3 - hardwire XON=1, support XADC - - sys_tst_rlink_n4 - support XADC and RGBLEDs - - sys_w11a_b3 - hardwire XON=1, support XADC; 72 MHz now - - sys_w11a_n4 - support XADC - - tools/bin - - tbrun_tbw - add vivado xsim and Makefile.ise support - - tbrun_tbwrri - use --sxon and --hxon instead of --xon - - tbw - add XSim support - - ti_w11 - add arty support, add -fx - - vbomconv - add [ise,viv]; add @uut tag handling; - add preliminary --(vsyn|vsim)_export; - add vivado xsim support; - - xtwi,xtwv - add BARE_PATH to provide clean environment - - - Bug fixes - - tools/tcl/rutil - - regdsc.tcl - regdsc: fix variable name in error msg - - - Known issues - - all issues: see README_known_issues.txt - - resolved issues: - - V0.64-4: support added for Vivado xsim. See however issue V0.72-1+2. - - V0.64-5: w11a_tb_guide.txt covers xsim tests too. - - - new issues: - - V0.72-1: Vivado 2015.4 xelab crashes when DPI is used in a mxied - vhdl-verilog language environment. This prevents currently to - build a xsim simulation model for rlink based test benches. - - V0.72-2: xsim simulations with timing annotation not yet available. - -- trunk (2015-12-30: svn rev 34(oc) 722(wfjm); untagged w11a_V0.71) +++++++++ - - Preface - - the w11a so far lacked any 'hardware debugger' support, which made the - debugging of CPU core issues a bit tedious. This release added a first - implementation of CPU debugger and monitoring features - - dmhbpt: hardware break point unit. Allows to set multiple break points - on instruction fetches (thus code break points) and on data - reads/writes (thus data access break points). The number of - breakpoints is configurable between 0 and 4, in current - designs 2 are available - - dmcmon: CPU state monitor. A buffer of configurable size which holds - a wide range of information on execution of the most recent - instructions. Tracing can be a instruction as well as on - micro cycle level. - - dmscnt: micro state counter. A counter array which allows to monitor - in which micro state the CPU time is spend, separated for - kernel and supervisor/user mode. - These three units together with the already existing ibus monitor allow - a very detailed and specific monitoring and debugging of the CPU. - - The w11a CPU core is not functionally modified in this release, the only - exception is the suspend logic needed to implement hardware break points. - Both the hardware break point and the instruction level tracing in dmcmon - require a clean definition of instruction boundaries, which the current - w11a core does not provide in some cases. This leads to imprecise - breakpoints (CPU executes one additional instruction) and incomplete - dmcmon traces (at instruction level when exceptions are taken). - - The w11a core will be modified in the next release to handle the above - mentioned conditions properly. The dmhbpt and dmcmon will be fully - documented when the w11a core changes are done, they work as expected - under all conditions, and the full back end integration is completed. - - - bottom line is that this release has little added value for normal w11 - usage. It is technically necessary to separate the addition of all - the debug units and modification of the CPU core into two releases. - - - Summary - - new reference system - - switched to Vivado 2015.4 (from 2014.4) - Note: 2015.4 has WebPACK support for Logic Analyser and HLS. Both are - not used so far, but the logic analyser may come in handy soon. - - switched to tcl8.6 (from tcl8.5) - Note: tcl8.6 is default tcl in Ubuntu 2014.04LTS, but up to now the - tclshcpp helper was linked against tcl8.5. So far no tcl8.6 - langauge features are used, but may be in future. - - - New features - - new modules - - rtl/w11a - - pdp11_dmcmon - pdp11: debug&moni: cpu monitor - - pdp11_dmhbpt - pdp11: debug&moni: hardware breakpoint - - pdp11_dmhbpt_unit - pdp11: dmhbpt - individual unit - - pdp11_dmscnt - pdp11: debug&moni: state counter - - new files - - tools/bin - - dmscntanal - analyze dmscnt data - - dmscntconv - convert dmscnt data - - tools/asm-11/lib - - defs_mmu.mac - definitions for mmu registers - - defs_nzvc.mac - definitions for condition code combos - - defs_reg70.mac - definitions for 11/70 CPU registers - - tcode_std_base.mac - Default tcode base code for simple tests - - tcode_std_start.mac - Default tcode startup code - - vec_devcatch.mac - vector catcher for device interrupts - - vec_devcatch_reset.mac - re-write vector catcher - - tools/tbench - - w11a_cmon - directory with dmcmon tests - - w11a_hbpt - directory with dmhbpt tests - - tools/tcl - - ibd_(dl|lp|pc|rk|rl)11 - directory with register regdsc's - - tools/tcl/rutil - - fileio.tcl - new tofile and fromfile procs - - tools/tcl/rw11 - - dmcmon.tcl - support code for dmcmon - - dmhbpt.tcl - support code for dmhbpt - - dmscnt.tcl - support code for dmscnt - - shell.tcl - new w11a tcl shell - - shell_egd.tcl - code for e,g,d commands - - tools/tcl/rw11util - - regmap.tcl - support for 'map of regdsc' definitions - - - Changes - - rtl/vlib/rlink - - rlink_core.vhd - add proc_sres: strip 'x' from RB_SRES.dout - - rtl/vlib/rlink/tb - - tbcore_rlink - drive SB_CNTL from start to avoid 'U' - - rtl/w11a - - pdp11 - add defs for pdp11_dm(scnt|hbpt|cmon) - - pdp11_* - add support for pdp11_dm(scnt|hbpt|cmon) - - rtl/sys_gen/w11a/* - - sys_conf - add sys_conf_(dmscnt|dmhbpt*|dmcmon*) - - rtl/sys_gen/w11a/*/tb - - sys_conf_sim - add sys_conf_(dmscnt|dmhbpt*|dmcmon*) - - tools/bin/ - - ti_w11 - add -ghw option - - tmuconv - fix '.' handling for br/sob instructions - correct xor (now r,dst, and not src,r) - - tools/tcl/rutil - - regdsc.tcl - add regbldkv,reggetkv - - util.tcl - rename optlist2arr->args2opts, new logic - - tools/tcl/rw11 - - asm.tcl - new arg list format in asm(run|treg|tmem) - - dasm.tcl - add dasm_inst2txt - - tools/tcl/ibd_ibmon - - util.tcl - add symbolic register dump - - - Bug fixes - - rtl/bplib/micron - - mt45w8mw16b - fix issue when 1st access is to addr 0 - - rtl/bplib/nxcramlib - - nx_cram_memctl_as - always define imem_oe in do_dispatch() - - rtl/ibus - - ibdr_tm11 - add missing BESET to sensitivity list - - rtl/w11a - - pdp11_sequencer - proper trap_mmu and trap_ysv handling - - tools/bin - - asm-11 - fix '.' handling in instructions - - - Known issues - - all issues: see README_known_issues.txt - -- w11a_V0.7 (2015-06-21) +++++++++++++++++++++++++++++++++++++++++++++++++++++ - cummulative summary of key changes from w11a_V0.6 to w11a_V0.7 - - Bugfix for DIV instruction (in w11a_V0.61, see ECO-026-div.txt) - - revised rbus protocol V4 (in w11a_V0.62, see README_Rlink_V4.txt) - - add basic Vivado support (in w11a_V0.64) - - add Nexys4 and Basys3 port of w11a (in w11a_V0.64) - - add RL11/RL02 disk support (in w11a_V0.64) - - add RH70+RP/RM disk support (in w11a_V0.65) - - add TM11/TY10 tape support (in w11a_V0.66) - - reference system now ISE 14.7, Vivado 2014.4; Ubuntu 14.04 64 bit, ghdl 0.31 - - for details see README-w11a_V.60-w11a_V0.70.txt - -- w11a_V0.6 (2014-06-06) +++++++++++++++++++++++++++++++++++++++++++++++++++++ - - cummulative summary of key changes from w11a_V0.5 to w11a_V0.6 - - revised ibus protocol V2 (in w11a_V0.51) - - revised rbus protocol V3 (in w11a_V0.52) - - backend server rewritten in C++ and Tcl (in w11a_V0.53 and w11a_V0.562) - - add Nexys3 port of w11a (in w11a_V0.54) - - add Cypress FX2 support (in w11a_V0.56 and w11a_V0.57) - - added LP11,PC11 support (in w11a_V0.58) - - reference system now ISE 14.7 and Ubuntu 12.04 64 bit, ghdl 0.31 - - many code cleanups; use numeric_std - - many documentation improvements - - development status upgraded to beta (from alpha) - - for details see README-w11a_V.50-w11a_V0.60.txt - -- w11a_V0.5 (2010-07-23) +++++++++++++++++++++++++++++++++++++++++++++++++++++ - - Initial release with - - w11a CPU core - - basic set of peripherals: kw11l, dl11, lp11, pc11, rk11/rk05 - - just for fun: iist (not fully implemented and tested yet) - - two complete system configurations with - - for a Digilent S3board rtl/sys_gen/w11a/s3board/sys_w11a_s3 - - for a Digilent Nexys2 rtl/sys_gen/w11a/nexys2/sys_w11a_n2 diff --git a/doc/README_Rlink_V4.md b/doc/README_Rlink_V4.md new file mode 100644 index 00000000..63b85886 --- /dev/null +++ b/doc/README_Rlink_V4.md @@ -0,0 +1,87 @@ +## Summary of changes for rlink v3 to v4 + +### Background +The protocol was initially designed as debug interface used over serial +port connections. From the beginning the protocol had crc error checking +and a simple error recovery mechanism. +When the protocol was used in the IO emulation of the w11, features like +block transfers, attentions, and command groups were added. Over time the +original simple concept for error recovery became practically unusable. +When the protocol was used on boards with a Cypress FX2 USB interface +the number of round trips became the sole performance limiting factor. + +### Goals for rlink v4 +- 16 bit addresses (instead of 8 bit) +- more robust encoding, support for error recovery at transport level +- add features to reduce round trips + - improved attention handling + - new 'list abort' command + +### Changes in detail + +#### Encoding +- framing (comma) char representation changed + - now 2 byte sequence for comma char, with internal redundancy + - optimized for robustness. Also more compact for larger `rblk`/`wblk`. + +#### Framing +- unexpected `EOP` in `sl_idle` now silently ignored + + --> before: send NAK+EOP + --> now allows to send EOP+NAK to start a retransmit + +- command aborts send now an error code, the abort sequence + + NAK EOP + +- the nakbyte has the redundant format + + 10 + +- the abort sequence sequence is not protected by a crc, but has enough + redundancy that transmission errors can be detected. +- all unexpected commas after `SOP` will cause an abort. This adds robustness + in case transmission error converts a data byte into a comma. + +#### Commands +- 16 bit addresses +- 16 bit `rblk`/`wblk` transfer size counts. Now cnt rather cnt-1 used. +- `rblk`/`wblk` now return 'done count', number of successfully transfered + words Note: rblk always transfers cnt words, rest is padded. +- `babo` state flag added + - `babo` is cleared when `rblk`/`wblk` is started, and set when they + are aborted + - `babo` is not changed by commands other then rblk and wblk +- `stat` command removed (functionality not needed anymore) +- `labo` command added + - returns the babo flag + - if babo set, all remaining commands in the list will be ignored +- `stat` byte layout changed + - `cerr` and `derr` flags removed (not needed anymore) + - now 4 (instead of 3) external `RB_STAT` bit +- 16 bit crc used (instead of 8 bit) + +#### attn handling +- a message with the current attn pattern is send, not only an attn comma. + This give the attn handler a priori knowledge of `LAM` sources. + An `attn` command must still be used to harvest the attn pattern. +- attn poll always returns attn notify, usage of idle comma removed + +#### General +- reserve 0xff00-0xffff range for rlink system usage +- implement 4 default registers (in rlink_core) + + ffff cntl + fffe stat (holds rtbuf size) + fffc/d sysid (32 bit system identifier) + +- rlink initialization now via wreg, not with `init` anymore +- has now retransmit buffer, size configurable (2,4,8,.. kB) +- used for `wblk` dcrc validation in addition +- a `NAK` outside a `SOP`/`EOP` frame will trigger a retransmit of last + response +- retransmit buffer cleared when first cmd processed + + --> an empty SOP-EOP does not reset the retransmit buffer + +- no internal/external `init` distinction, 'we' always 0 when init=1 diff --git a/doc/README_Rlink_V4.txt b/doc/README_Rlink_V4.txt deleted file mode 100644 index ffecb920..00000000 --- a/doc/README_Rlink_V4.txt +++ /dev/null @@ -1,76 +0,0 @@ -$Id: README_Rlink_V4.txt 614 2014-12-20 15:00:45Z mueller $ - -Summary of changes for rlink v3 to v4 - -Background - The protocol was initially designed as debug interface used over serial - port connections. From the beginning the protocol had crc error checking - and a simple error recovery mechanism. - When the protocol was used in the IO emulation of the w11, features like - block transfers, attentions, and command groups were added. Over time the - original simple concept for error recovery became practically unusable. - When the protocol was used on boards with a Cypress FX2 USB interface - the number of round trips became the sole performance limiting factor. - -Goals for rlink v4 - - 16 bit addresses (instead of 8 bit) - - more robust encoding, support for error recovery at transport level - - add features to reduce round trips - - improved attention handling - - new 'list abort' command - -Changes in detail - - - encoding - - framing (comma) char representation changed - - now 2 byte sequence for comma char, with internal redundancy - - optimized for robustness. Also more compact for larger rblk/wblk. - - - framing - - unexpected EOP in sl_idle now silently ignored - --> before: send NAK+EOP - --> now allows to send EOP+NAK to start a retransmit - - command aborts send now an error code, the abort sequence - NAK EOP - - the nakbyte has the redundant format - 10 - - the abort sequence sequence is not protected by a crc, but has enough - redundancy that transmission errors can be detected. - - all unexpected commas after SOP will cause an abort. This adds robustness - in case transmission error converts a data byte into a comma. - - - commands - - 16 bit addresses - - 16 bit rblk/wblk transfer size counts. Now cnt rather cnt-1 used. - - rblk/wblk now return 'done count', number of successfully transfered words - Note: rblk always transfers cnt words, rest is padded. - - babo state flag added - - babo is cleared when rblk/wblk is started, and set when they are aborted - - babo is not changed by commands other then rblk and wblk - - stat command removed (functionality not needed anymore) - - labo command added - - returns the babo flag - - if babo set, all remaining commands in the list will be ignored - - stat byte layout changed - - cerr and derr flags removed (not needed anymore) - - now 4 (instead of 3) external RB_STAT bit - - 16 bit crc used (instead of 8 bit) - - attn handling - - a message with the current attn pattern is send, not only an attn comma. - This give the attn handler a priori knowledge of LAM sources. - An attn command must still be used to harvest the attn pattern. - - attn poll always returns attn notify, usage of idle comma removed - - - general - - reserve 0xff00-0xffff range for rlink system usage - - implement 4 default registers (in rlink_core) - ffff cntl - fffe stat (holds rtbuf size) - fffc/d sysid (32 bit system identifier) - - rlink initialization now via wreg, not with init anymore - - has now retransmit buffer, size configurable (2,4,8,.. kB) - - used for wblk dcrc validation in addition - - a NAK outside a SOP/EOP frame will trigger a retransmit of last response - - retransmit buffer cleared when first cmd processed - -> an empty SOP-EOP does not reset the retransmit buffer - - no internal/external init distinction, 'we' always 0 when init=1 diff --git a/doc/README_USB-VID-PID.md b/doc/README_USB-VID-PID.md new file mode 100644 index 00000000..ba1233ce --- /dev/null +++ b/doc/README_USB-VID-PID.md @@ -0,0 +1,58 @@ +# Note on USB VID and PID + +**!! Read this disclaimer carefully. You'll be responsible for** +**!! any misuse of the defaults provided with the project sources.** + +USB drivers identify hardware by means of two 16 bit identifiers + + VID - Vendor ID + PID - Product ID + +In a 'softcoded' USB Controler like the Cypress FX2 each firmware with a +specific functionality should have a unique VID/PID so that drivers can +automatically detect and configure. + +The assignment of USB VID/PID is done by usb.org. Unfortunately there is no +VID range reserved for 'development' or 'internal use', the only official way +to obtain a VID is to buy one from usb.org, see +http://www.usb.org/developers/vendor/ + +The `usb_jtag` project bought many years ago a small PID range from a re-seller +and used + + VID=16C0 + PID=06AD + +for a project which implemented an Altera UsbBlaster compatible JTAG interface. + +The firmware provided with this project provides +- a JTAG interface (via EP1 and EP2) +- data channels (via EP4, EP6 and optionally EP8) +The JTAG part is compatible with the `usb_jtag` implementation and by extension +compatible with the `usbblaster` cable driver provided by `UrJtag`, and can +therefore be operated with the `jtag` command. + +However, because the firmware offers additional functionality it should have a +separate VID/PID. Unfortunately it is not longer possible to buy at very modest +cost a PID sub-range, as was done by the `usb_jtag` project bought many years +ago. + +VOTI, a small dutch company, has bought a VID for it's own developments and +made a small range of PID publicly available as ***free for internal lab use***. +Usage is granted for ***internal lab use only*** by VOTI under the conditions: +- the gadgets in which you use those PIDs do not leave your desk +- you won't complain to VOTI if you get in trouble with duplicate PIDs + (for instance because someone else did not follow the previous rule). +- See http://www.voti.nl/pids/pidfaq.html for further details. + +The retro11 project uses one of these ***free for internal lab use*** PIDs + + VID=16C0 + PID=03EF + +from VOTI as default VID/PID. + +So keep in mind +- **This is is perfectly fine for plain hobbyist usage** +- **But respect the ownership of VOTI of this VID/PID and do not + use this VID/PID for other purposes!** diff --git a/doc/README_USB-VID-PID.txt b/doc/README_USB-VID-PID.txt deleted file mode 100644 index c0b6cbab..00000000 --- a/doc/README_USB-VID-PID.txt +++ /dev/null @@ -1,55 +0,0 @@ -# $Id: README_USB-VID-PID.txt 467 2013-01-02 19:49:05Z mueller $ - -!! Read this disclaimer carefully. You'll be responsible for any !! -!! misuse of the defaults provided with the project sources. !! - -USB drivers identify hardware by means of two 16 bit identifiers - - VID - Vendor ID - PID - Product ID - -In a 'softcoded' USB Controler like the Cypress FX2 each firmware with a -specific functionality should have a unique VID/PID so that drivers can -automatically detect and configure. - -The assignment of USB VID/PID is done by usb.org. Unfortunately there is no -VID range reserved for 'development' or 'internal use', the only official way -to obtain a VID is to buy one from usb.org, see - http://www.usb.org/developers/vendor/ - -The 'usb_jtag' project bought many years ago a small PID range from a re-seller -and used - VID=16C0 - PID=06AD -for a project which implemented an Altera UsbBlaster compatible JTAG interface. - -The firmware provided with this project provides - - a JTAG interface (via EP1 and EP2) - - data channels (via EP4, EP6 and optionally EP8) -The JTAG part is compatible with the 'usb_jtag' implementation and by extension -compatible with the 'usbblaster' cable driver provided by 'UrJtag', and can -therefore be operated with the 'jtag' command. - -However, because the firmware offers additional functionality it should have a -separate VID/PID. Unfortunately it is not longer possible to buy at very modest -cost a PID sub-range, as was done by the 'usb_jtag' project bought many years -ago. - -VOTI, a small dutch company, has bought a VID for it's own developments and -made a small range of PID publicly available as "free for internal lab use". -Usage is granted for 'internal lab use only' by VOTI under the conditions: - - the gadgets in which you use those PIDs do not leave your desk - - you won't complain to VOTI if you get in trouble with duplicate PIDs - (for instance because someone else did not follow the previous rule). - - See http://www.voti.nl/pids/pidfaq.html for further details. - -The retro11 project uses one of these 'free for internal lab use' PIDs - - VID=16C0 - PID=03EF - -from VOTI as default VID/PID. - -==> This is is perfectly fine for plain hobbyist usage -==> But respect the ownership of VOTI of this VID/PID and do not - use this VID/PID for other purposes diff --git a/doc/README_buildsystem_ISE.md b/doc/README_buildsystem_ISE.md new file mode 100644 index 00000000..979f903b --- /dev/null +++ b/doc/README_buildsystem_ISE.md @@ -0,0 +1,246 @@ +## Guide to the Build System (Xilinx ISE Version) + +### Table of content + +- [Concept](#user-content-concept) +- [Setup system environment](#user-content-sysenv) + - [Setup environment variables](#user-content-envvar) + - [Compile UNISIM/UNIMACRO/SIMPRIM libraries for ghdl](#user-content-ghdllibs) +- [Building test benches](#user-content-buildtb) + - [With ghdl](#user-content-buildtb-ghdl) + - [With ISE ISim](#user-content-buildtb-isim) +- [Building FPGA bit files](#user-content-buildfpga) +- [Configuring FPGAs (via make flow)](#user-content-config-make) +- [Configuring FPGAs (directly via config_wrapper)](#user-content-config-wrap) +- [Note on Artix-7 based designs](#user-content-artix) + +### Concept + +This projects uses GNU make to +- generate bit files (synthesis with xst and place&route with par) +- generate test benches (with ghdl or Xilinx ISim) +- configure the FPGA (with Xilinx Impact or Linux jtag) + +The Makefile's in general contain only a few definitions, all the make logic +is concentrated in a few master makefiles which are included. + +Simulation and synthesis tools usually need a list of the VHDL source +files, often in proper compilation order (libraries before components). +The different tools have different formats of these 'project files'. + +The build system employed in this project is based on manifest files called + + 'vbom' or "VHDL bill of material" files + +which list for each vhdl source file the libraries and sources for the +instantiated components, the later via their vbom, and last but not least +the name of the vhdl source file. + +All file name are relative to the current directory. A recursive traversal +through all vbom's gives for each vhld module all sources needed to compile +it. The vbomconv script in tools/bin does this, and generates depending on +options +- make dependency files +- ISE xst project files (synthesis) +- ISE ISim project files (simulation) +- ghdl commands for analysis, inspection and make step + +The master make files contain pattern rules like + + %.ngc : %.vbom -- synthesize with xst + % : %.vbom -- build functional model test bench + +which encapsulate all the vbomconv magic + +A full w11a system is build from about 100 source files, test benches +from even more. Using the vbom's a large number of designs can be easily +maintained. + +For more details on vbomconv consult the man page. + +### Setup system environment + +#### Setup environment variables + +The build flows require the environment variables: +- `RETROBASE`: must refer to the installation root directory +- `XTWI_PATH`: install path of the ISE version, without `/ISE_DS/` ! +- `RETRO_FX2_VID` and `RETRO_FX2_PID`: default USB VID/PID for Cypress FX2 + +For general instructions on environment see [INSTALL.md](INSTALL.md) . +For details on `RETRO_FX2_VID` and `RETRO_FX2_PID` see +[INSTALL_fx2_support.md](INSTALL_fx2_support.md). + +Notes: +- The build system uses a small wrapper script called `xtwi` to encapsulate + the Xilinx environment. It uses `XTWI_PATH` to setup the ISE environment on + the fly. For details consult 'man xtwi'. +- don't run the ISE setup scripts ..../settings(32|64).sh in your working + shell. Setup only `XTWI_PATH` ! + +#### Compile UNISIM/UNIMACRO/SIMPRIM libraries for ghdl + +A few entities use `UNISIM` or `UNIMACRO` primitives, and models derived after +the par step require also `SIMPRIM` primitives. In these cases ghdl has to +link against a compiled `UNISIM`, `UNIMACRO` or `SIMPRIM` libraries. + +To make handling of the parallel installation of several ISE versions +easy the compiled libraries are stored in sub-directories under `$XILINX`: + + $XILINX/ghdl/unisim + $XILINX/ghdl/unimacro + $XILINX/ghdl/simprim + +Two helper scripts will create these libraries: + + cd $RETROBASE + xise_ghdl_unisim # does UNISIM and UNIMACRO + xise_ghdl_simprim # does SIMPRIM + +Run these scripts for each ISE version which is installed. + +### Building test benches + +The build flows support two simulators +- ghdl -> open source, with VHPI support, doesn't accept sdf files +- ISE ISim -> limited to 50k lines in WebPack, no VHPI support + +#### With ghdl + +To compile a ghdl based test bench named `` all is needed is + + make + +The make file will use `.vbom`, create all make dependency files, +and generate the needed ghdl commands. + +In many cases the test benches can also be compiled against the gate +level models derived after the `xst`, `map` or `par` step. To compile them + + make _ssim # for post-xst (using UNISIM) + make _fsim # for post-map (using SIMPRIM) + make _tsim # for post-par (using SIMPRIM) + +Individual working directories are used for the different models + + ghdl.bsim for bahavioral model + ghdl.ssim for post-xst + ghdl.fsim for post-map + ghdl.tsim for post-par + +and can co-exist. The `make ghdl_tmp_clean` can be used to flush the ghdl +work areas, but in general this is not needed (since V0.73). + +Notes: +- the post-xst simulation (_ssim targets) proved to be a valuable tool. +- ghdl fails to read sdf files generated by Xilinx tools, and thus does + not support a post-par simulation with full timing. +- post-par simulations without timing annotation often fail, most likely + due to clocking and delta cycle issues due to inserted clock buffers. + +#### With ISE ISim + +To compile a ISE ISim based test bench named `` all is needed is + + make _ISim + +The make file will use `.vbom`, create all make dependency files, +and generate the needed ISE ISim project files and commands. + +In many cases the test benches can also be compiled against the gate +level models derived after the xst, map or par step. To compile them + + make ise_tmp_clean + make _ISim_ssim # for post-xst + make _ISim_fsim # for post-map + make _ISim_tsim # for post-par + +Notes: +- ISim in ISE WebPack is limited to about 50k lines source code. That is + enough for many functional simulations, a w11a system has about 27k lines, + the test bench adds another 3k lines. But the limit gets quickly exceeded + with post-xst and especially post-par models. If the limit is exceeded, the + simulation engine throttles to snails speed. +- ISim does not support VHPI (interfacing of external C routines to VHDL). + Since VHPI is used in the rlink simulation all system test benches with + an rlink interface, thus most, will only run with ghdl and not with ISim. + +### Building FPGA bit files + +To generate a bit file for a system named `` all is needed is + + make .bit + +The make file will use `.vbom`, create all make dependency files, build +the ucf file with cpp, and run the synthesis flow (`xst`, `ngdbuild`, `par`, +`trce`). The log files will be conveniently renamed + + _xst.log # xst log file + _tra.log # translate (ngdbuild) log file (renamed %.bld) + _map.log # map log file (renamed %_map.mrp) + _par.log # par log file (renamed %.par) + _pad.log # pad file (renamed %_pad.txt) + _twr.log # trce log file (renamed %.twr) + _tsi.log # trce tsi file (renamed %.tsi) + _bgn.log # bitgen log file (renamed %.bgn) + +If only the xst or par output is wanted just use + + make .ngc + make .ncd + +Some tools require a `.svf` rather than a `.bit` file. It can be created with + + make .svf + +A simple 'message filter' system is also integrated into the make build flow. +For many (though not all) systems a `.mfset` file has been provided which +defines the `xst`, `par` and `bitgen` messages which are considered ok. To see +only the remaining message extracted from the various `.log` files simply +use the make target + + make .mfsum + +after a re-build. + +### Configuring FPGAs (via make flow) + +The make flow supports also loading the bitstream into FPGAs, either +via Xilinx Impact, or via the Cypress FX2 USB controller is available. + +For Xilinx Impact a Xilinx USB Cable II has to be properly setup, than +simply use + + make .iconfig + +For using the Cypress FX2 USB controller on Digilent Nexys2, Nexys3 and +Atlys boards just connect the USB cable and + + make .jconfig + +This will automatically check and optionally re-load the FX2 firmware +to a version matching the FPGA design, generate a .svf file from the +.bit file, and configure the FPGA. In case the bit file is out-of-date +the whole design will be re-implemented before. + +### Configuring FPGAs (directly via `config_wrapper`) + +The make flow described above uses two scripts + + config_wrapper # must be used with xtwi ! + fx2load_wrapper + +which can be used directly for loading available bit or svf files into +the FPGA. For detailed documentation see the respective man pages. + +### Note on Artix-7 based designs + +The development for Nexys4 started with ISE, but has now fully moved to +Vivado. The make files for the ISE build flows have been kept for comparison +are have the name `Makefile.ise`. So for some Nexys4 designs and associated +one can still start with a + + make -f Makefile.ise + +an ISE based build. To be used for tool comparisons, the ISE generated bit +files were never tested in an FPGA. diff --git a/doc/README_buildsystem_ISE.txt b/doc/README_buildsystem_ISE.txt deleted file mode 100644 index 6ef13ffe..00000000 --- a/doc/README_buildsystem_ISE.txt +++ /dev/null @@ -1,239 +0,0 @@ -# $Id: README_buildsystem_ISE.txt 779 2016-06-26 15:37:16Z mueller $ - -Guide to the Build System (Xilinx ISE Version) - - Table of content: - - 1. Concept - 2. Setup system environment - a. Setup environment variables - b. Compile UNISIM/UNIMACRO/SIMPRIM libraries for ghdl - 3. Building test benches - a. With ghdl - b. With ISE ISim - 4. Building systems - 5. Configuring FPGAs (via make flow) - 6. Configuring FPGAs (directly via config_wrapper) - 7. Note on Artix-7 based designs - -1. Concept ---------------------------------------------------------------- - - This projects uses GNU make to - - generate bit files (synthesis with xst and place&route with par) - - generate test benches (with ghdl or Xilinx ISim) - - configure the FPGA (with Xilinx Impact or Linux jtag) - - The Makefile's in general contain only a few definitions, all the make logic - is concentrated in a few master makefiles which are included. - - Simulation and synthesis tools usually need a list of the VHDL source - files, often in proper compilation order (libraries before components). - The different tools have different formats of these 'project files'. - - The build system employed in this project is based on manifest files called - 'vbom' or "VHDL bill of material" files - which list for each vhdl source file the libraries and sources for the - instantiated components, the later via their vbom, and last but not least - the name of the vhdl source file. - All file name are relative to the current directory. A recursive traversal - through all vbom's gives for each vhld module all sources needed to compile - it. The vbomconv script in tools/bin does this, and generates depending on - options - - make dependency files - - ISE xst project files (synthesis) - - ISE ISim project files (simulation) - - ghdl commands for analysis, inspection and make step - - The master make files contain pattern rules like - %.ngc : %.vbom -- synthesize with xst - % : %.vbom -- build functional model test bench - which encapsulate all the vbomconv magic - - A full w11a system is build from about 100 source files, test benches - from even more. Using the vbom's a large number of designs can be easily - maintained. - - For more details on vbomconv consult the man page. - -2. Setup system environment ----------------------------------------------- - -2a. Setup environment variables -------------------------------------- - - The build flows require the environment variables: - - - RETROBASE: must refer to the installation root directory - - XTWI_PATH: install path of the ISE version, without /ISE_DS/ ! - - RETRO_FX2_VID and RETRO_FX2_PID: default USB VID/PID for Cypress FX2 - - For general instructions on environment see INSTALL.txt . - For details on RETRO_FX2_VID and RETRO_FX2_PID see INSTALL_fx2.txt. - - Notes: - - The build system uses a small wrapper script called xtwi to encapsulate - the Xilinx environment. It uses XTWI_PATH to setup the ISE environment on - the fly. For details consult 'man xtwi'. - - don't run the ISE setup scripts ..../settings(32|64).sh in your working - shell. Setup only XTWI_PATH ! - -2b. Compile UNISIM/UNIMACRO/SIMPRIM libraries for ghdl --------------- - - A few entities use UNISIM or UNIMACRO primitives, and models derived after - the par step require also SIMPRIM primitives. In these cases ghdl has to - link against a compiled UNISIM, UNIMACRO or SIMPRIM libraries. - - To make handling of the parallel installation of several ISE versions - easy the compiled libraries are stored in sub-directories under $XILINX: - - $XILINX/ghdl/unisim - $XILINX/ghdl/unimacro - $XILINX/ghdl/simprim - - Two helper scripts will create these libraries: - - cd $RETROBASE - xise_ghdl_unisim # does UNISIM and UNIMACRO - xise_ghdl_simprim # does SIMPRIM - - Run these scripts for each ISE version which is installed. - -3. Building test benches -------------------------------------------------- - - The build flows support two simulators - - ghdl -> open source, with VHPI support, doesn't accept sdf files - - ISE ISim -> limited to 50k lines in WebPack, no VHPI support - -3a. With ghdl -------------------------------------------------------- - - To compile a ghdl based test bench named all is needed is - - make - - The make file will use .vbom, create all make dependency files, - and generate the needed ghdl commands. - - In many cases the test benches can also be compiled against the gate - level models derived after the xst, map or par step. To compile them - - make _ssim # for post-xst (using UNISIM) - make _fsim # for post-map (using SIMPRIM) - make _tsim # for post-par (using SIMPRIM) - - Individual working directories are used for the different models - ghdl.bsim for bahavioral model - ghdl.ssim for post-xst - ghdl.fsim for post-map - ghdl.tsim for post-par - and can co-exist. The 'make ghdl_tmp_clean' can be used to flush the ghdl - work areas, but in general this is not needed (since V0.73). - - Notes: - - the post-xst simulation (_ssim targets) proved to be a valuable tool. - - ghdl fails to read sdf files generated by Xilinx tools, and thus does - not support a post-par simulation with full timing. - - post-par simulations without timing annotation often fail, most likely - due to clocking and delta cycle issues due to inserted clock buffers. - -3b. With ISE ISim ---------------------------------------------------- - - To compile a ISE ISim based test bench named all is needed is - - make _ISim - - The make file will use .vbom, create all make dependency files, - and generate the needed ISE ISim project files and commands. - - In many cases the test benches can also be compiled against the gate - level models derived after the xst, map or par step. To compile them - - make ise_tmp_clean - make _ISim_ssim # for post-xst - make _ISim_fsim # for post-map - make _ISim_tsim # for post-par - - Notes: - - ISim in ISE WebPack is limited to about 50k lines source code. That is - enough for many functional simulations, a w11a system has about 27k lines, - the test bench adds another 3k lines. But the limit gets quickly exceeded - with post-xst and especially post-par models. If the limit is exceeded, the - simulation engine throttles to snails speed. - - ISim does not support VHPI (interfacing of external C routines to VHDL). - Since VHPI is used in the rlink simulation all system test benches with - an rlink interface, thus most, will only run with ghdl and not with ISim. - -4. Building systems ------------------------------------------------------- - - To generate a bit file for a system named all is needed is - - make .bit - - The make file will use .vbom, create all make dependency files, build - the ucf file with cpp, and run the synthesis flow (xst, ngdbuild, par, trce). - The log files will be conveniently renamed - - _xst.log # xst log file - _tra.log # translate (ngdbuild) log file (renamed %.bld) - _map.log # map log file (renamed %_map.mrp) - _par.log # par log file (renamed %.par) - _pad.log # pad file (renamed %_pad.txt) - _twr.log # trce log file (renamed %.twr) - _tsi.log # trce tsi file (renamed %.tsi) - _bgn.log # bitgen log file (renamed %.bgn) - - If only the xst or par output is wanted just use - - make .ngc - make .ncd - - Some tools require a .svf rather than a .bit file. It can be created with - - make .svf - - A simple 'message filter' system is also integrated into the make build flow. - For many (though not all) systems a .mfset file has been provided which - defines the xst,par and bitgen messages which are considered ok. To see - only the remaining message extracted from the various .log files simply - use the make target - - make .mfsum - - after a re-build. - -5. Configuring FPGAs (via make flow) -------------------------------------- - - The make flow supports also loading the bitstream into FPGAs, either - via Xilinx Impact, or via the Cypress FX2 USB controller is available. - - For Xilinx Impact a Xilinx USB Cable II has to be properly setup, than - simply use - - make .iconfig - - For using the Cypress FX2 USB controller on Digilent Nexys2, Nexys3 and - Atlys boards just connect the USB cable and - - make .jconfig - - This will automatically check and optionally re-load the FX2 firmware - to a version matching the FPGA design, generate a .svf file from the - .bit file, and configure the FPGA. In case the bit file is out-of-date - the whole design will be re-implemented before. - -6. Configuring FPGAs (directly via config_wrapper) ------------------------- - - The make flow described above uses two scripts - config_wrapper # must be used with xtwi ! - fx2load_wrapper - which can be used directly for loading available bit or svf files into - the FPGA. For detailed documentation see the respective man pages. - -7. Note on Artix-7 based designs ------------------------------------------ - - The development for Nexys4 started with ISE, but has now fully moved to - Vivado. The make files for the ISE build flows have been kept for comparison - are have the name Makefile.ise. So for some Nexys4 designs and associated - one can still start with a - - make -f Makefile.ise - - an ISE based build. To be used for tool comparisons, the ISE generated bit - files were never tested in an FPGA. diff --git a/doc/README_buildsystem_Vivado.md b/doc/README_buildsystem_Vivado.md new file mode 100644 index 00000000..fcc7dee8 --- /dev/null +++ b/doc/README_buildsystem_Vivado.md @@ -0,0 +1,274 @@ +## Guide to the Build System (Xilinx Vivado Version) + +### Table of content + +- [Concept](#user-content-concept) +- [Setup system environment](#user-content-sysenv) + - [Setup environment variables](#user-content-envvar) + - [Compile UNISIM/UNIMACRO libraries for ghdl](#user-content-ghdllibs) +- [Building test benches](#user-content-buildtb) + - [With ghdl](#user-content-buildtb-ghdl) + - [With Vivado xsim](#user-content-buildtb-xsim) +- [Building FPGA bit files](#user-content-buildfpga) +- [Building vivado projects, creating models](#user-content-buildviv) +- [Configuring FPGAs (via make flow)](#user-content-config-fpga) +- [Note on ISE](#user-content-ise) + +### Concept + +This projects uses GNU `make` to +- generate bit files (with Vivado synthesis) +- generate test benches (with ghdl or Vivado XSim) +- configure the FPGA (with Vivado hardware server) + +The Makefile's in general contain only a few definitions. By far most of +the build flow logic in Vivado is in tcl scripts, only a thin interface +layer is needed at the make level, which is concentrated in a few master +makefiles which are included. + +Simulation and synthesis tools usually need a list of the VHDL source +files, sometimes in proper compilation order (libraries before components). +The different tools have different formats of these 'project descriptions. + +The build system employed in this project is based on manifest files called + + 'vbom' or "VHDL bill of material" files + +which list for each vhdl source file the libraries and sources for the +instantiated components, the later via their vbom, and last but not least +the name of the vhdl source file. + +All file name are relative to the current directory. A recursive traversal +through all vbom's gives for each vhld module all sources needed to compile +it. The `vbomconv` script in `tools/bin` does this, and generates depending on +options +- make dependency files +- Vivado synthesis setup files +- Vivado simulation setup files +- ghdl commands for analysis, inspection and make step + +The master make files contain pattern rules like + + %.bit : %.vbom -- create bit file + % : %.vbom -- build functional model test bench + +which encapsulate all the `vbomconv` magic + +A full w11a system is build from about 100 source files, test benches +from even more. Using the vbom's a large number of designs can be easily +maintained. + +For more details on `vbomconv` consult the man page. + +### Setup system environment + +#### Setup environment variables + +The build flows require the environment variables: +- `RETROBASE`: must refer to the installation root directory +- `XTWV_PATH`: install path of the Vivado version + +For general instructions on environment see [INSTALL.md](INSTALL.md). + +Notes: +- The build system uses a small wrapper script called xtwv to encapsulate + the Xilinx environment. It uses `XTWV_PATH` to setup the Vivado environment + on the fly. For details consult 'man xtwv'. +- don't run the Vivado setup scripts ..../settings(32|64).sh in your working + shell. Setup only XTWV_PATH ! + +#### Compile UNISIM/UNIMACRO libraries for ghdl + +A few entities use `UNISIM` or `UNIMACRO` primitives, and post synthesis models +require also `UNISIM` primitives. In these cases ghdl has to link against a +compiled `UNISIM` or `UNIMACRO` libraries. + +To make handling of the parallel installation of several Vivado versions +easy the compiled libraries are stored in sub-directories under `$XTWV_PATH`: + + $XTWV_PATH/ghdl/unisim + $XTWV_PATH/ghdl/unimacro + +A helper scripts will create these libraries: + + cd $RETROBASE + xviv_ghdl_unisim # does UNISIM and UNIMACRO + +Run these scripts for each Vivado version which is installed. + +Notes: +- Vivado supports `SIMPRIM` libraries only in Verilog form, there is no vhdl + version anymore. +- ghdl can therefore not be used to do timing simulations with Vivado. + However: under ISE `SIMPRIM` was available in vhdl, but ghdl did never + accept the sdf files, making ghdl timing simulations impossible under ISE too. + +### Building test benches + +The build flows currently supports ghdl and the vivado simulator xsim. + +#### With ghdl + +To compile a ghdl based test bench named `` all is needed is + + make + +The make file will use `.vbom`, create all make dependency files, +and generate the needed ghdl commands. + +In some cases the test benches can also be compiled against the gate +level models derived after the synthesis or optimize step. +Vivado only generated functional (`UNISIM` based) models in vhdl. Timing +(`SIMPRIM` based) models are only available on verilog. The combination +vivado + ghdl is therefore limited to functional model simulation. + +To compile them + + make ghdl_tmp_clean + make _ssim # for post synthesis functional + make _osim # for post optimize functional + make _rsim # for post routing functional + +Individual working directories are used for the different models + + ghdl.bsim for bahavioral model + ghdl.ssim for post synthesis + ghdl.osim for post optimize + ghdl.rsim for post routing + +and can co-exist. The `make ghdl_tmp_clean` can be used to flush the ghdl +work areas, but in general this is not needed (since V0.73). + +Notes: +- Many post-synthesis functional currently fail due to startup and + initialization problems (see issue V0.73-2). + +#### With Vivado xsim + +To compile a Vivado xsim based test bench named all is needed is + + make _XSim + +The make file will use `.vbom`, create all make dependency files, +and generate the needed Vivado xsim project files and commands. + +In many cases the test benches can also be compiled against the gate +level models derived after the synthesis, optimize or routing step. +Vivado supports functional (`UNISIM` based) models in vhdl and in verilog, +and timing (`SIMPRIM` based) models only in verilog. Since practice showed +that verilog models compile and execute faster, verilog is used for both +functional and timing models. + + make _XSim_ssim # for post-synthesis functional + make _XSim_osim # for post-optimize functional + make _XSim_rsim # for post-routing functional + + make _XSim_esim # for post-synthesis timing + make _XSim_psim # for post-optimize timing + make _XSim_tsim # for post-routing timing + +Notes: +- as of vivado 2016.2 `xelab` shows sometimes extremely long build times, + especially for generated post-synthesis vhdl models (see issue V0.73-1). +- Many post-synthesis functional and especially post-routing timing + simulations currently fail due to startup and initialization problems + (see issue V0.73-2). + +### Building FPGA bit files + +To generate a bit file for a system named `` all is needed is + + make .bit + +The make file will use `.vbom`, create all make dependency files and +starts Vivado in batch mode with the proper scripts which will handle the +build steps. The log files and reports are conveniently renamed + + _syn.log # synthesis log (from runme.log) + _imp.log # implementation log (from runme.log) + _bit.log # write_bitstream log (from runme.log) + + _syn_util.rpt # (from _utilization_synth.rpt) + _opt_drc.rpt # (from _opt_drc.rpt) + _pla_io.rpt # (from _io_placed.rpt) + _pla_clk.rpt # (from _clock_utilization_placed.rpt) + _pla_util.rpt # (from _utilization_placed.rpt) + _pla_cset.rpt # (from _control_sets_placed.rpt) + _rou_sta.rpt # (from _route_status.rpt) + _rou_drc.rpt # (from _drc_routed.rpt) + _rou_tim.rpt # (from _timing_summary_routed.rpt) + _rou_pwr.rpt # (from _power_routed.rpt) + _rou_util.rpt # (extra report_utilization) + _rou_util_h.rpt # (extra report_utilization -hierarchical) + _ds.rpt # (extra report_datasheet) + +The design check points are also kept + + _syn.dcp # (from .dcp) + _opt.dcp # (from _opt.dcp) + _pla.dcp # (from _placed.dcp) + _rou.dcp # (from _routed.dcp) + +If only the post synthesis, optimize or route design checkpoints are wanted + + make _syn.dcp + make _opt.dcp + make _rou.dcp + +### Building vivado projects, creating gate level models + +Vivado is used in 'project mode', whenever one of the targets mentioned +above is build a vivado project is freshly created in the directory + + project_mflow + +with the project file + + project_mflow/project_mflow.xpr + +There are many make targets which +- just create the project +- start vivado in gui mode to inspect the most recent project +- create gate level models + +Specifically + + make .vivado # create vivado project from .vbom + make vivado # open project in project_mflow + + make _ssim.vhd # post-synthesis functional model (vhdl) + make _osim.vhd # post-optimize functional model (vhdl) + make _rsim.vhd # post-routing functional model (vhdl) + + make _ssim.v # post-synthesis functional model (verilog) + make _osim.v # post-optimize functional model (verilog) + make _rsim.v # post-routing functional model (verilog) + + make _esim.v # post-synthesis timing model (verilog) + make _psim.v # post-optimize timing model (verilog) + make _tsim.v # post-routing timing model (verilog) + +For timing model verilog file an associated sdf file is also generated. + +### Configuring FPGAs + +The make flow supports also loading the bitstream into FPGAs via the +Vivado hardware server. Simply use + + make .vconfig + +Note: works with Arty, Basys3, and Nexys4, only one board must connected. + +### Note on ISE + +The development for Nexys4 started with ISE, but has now fully moved to +Vivado. The make files for the ISE build flows have been kept for comparison +are have the name `Makefile.ise`. So for some Nexys4 designs and associated +one can still start with a + + make -f Makefile.ise + or + makeise + +an ISE based build. To be used for tool comparisons, the ISE generated bit +files were never tested in an FPGA. diff --git a/doc/README_buildsystem_Vivado.txt b/doc/README_buildsystem_Vivado.txt deleted file mode 100644 index b58f2bef..00000000 --- a/doc/README_buildsystem_Vivado.txt +++ /dev/null @@ -1,267 +0,0 @@ -# $Id: README_buildsystem_Vivado.txt 779 2016-06-26 15:37:16Z mueller $ - -Guide to the Build System (Xilinx Vivado Version) - - Table of content: - - 1. Concept - 2. Setup system environment - a. Setup environment variables - b. Compile UNISIM/UNIMACRO libraries for ghdl - 3. Building test benches - a. With ghdl - b. With Vivado xsim - 4. Building systems - 5. Building vivado projects, creating gate level models - 6. Configuring FPGAs (via make flow) - 7. Note on ISE - -1. Concept ---------------------------------------------------------------- - - This projects uses GNU make to - - generate bit files (with Vivado synthesis) - - generate test benches (with ghdl or Vivado XSim) - - configure the FPGA (with Vivado hardware server) - - The Makefile's in general contain only a few definitions. By far most of - the build flow logic in Vivado is in tcl scripts, only a thin interface - layer is needed at the make level, which is concentrated in a few master - makefiles which are included. - - Simulation and synthesis tools usually need a list of the VHDL source - files, sometimes in proper compilation order (libraries before components). - The different tools have different formats of these 'project descriptions. - - The build system employed in this project is based on manifest files called - 'vbom' or "VHDL bill of material" files - which list for each vhdl source file the libraries and sources for the - instantiated components, the later via their vbom, and last but not least - the name of the vhdl source file. - All file name are relative to the current directory. A recursive traversal - through all vbom's gives for each vhld module all sources needed to compile - it. The vbomconv script in tools/bin does this, and generates depending on - options - - make dependency files - - Vivado synthesis setup files - - Vivado simulation setup files - - ghdl commands for analysis, inspection and make step - - The master make files contain pattern rules like - %.bit : %.vbom -- create bit file - % : %.vbom -- build functional model test bench - which encapsulate all the vbomconv magic - - A full w11a system is build from about 100 source files, test benches - from even more. Using the vbom's a large number of designs can be easily - maintained. - - For more details on vbomconv consult the man page. - -2. Setup system environment ----------------------------------------------- - -2a. Setup environment variables -------------------------------------- - - The build flows require the environment variables: - - - RETROBASE: must refer to the installation root directory - - XTWV_PATH: install path of the Vivado version - - For general instructions on environment see INSTALL.txt . - - Notes: - - The build system uses a small wrapper script called xtwv to encapsulate - the Xilinx environment. It uses XTWV_PATH to setup the Vivado environment - on the fly. For details consult 'man xtwv'. - - don't run the Vivado setup scripts ..../settings(32|64).sh in your working - shell. Setup only XTWV_PATH ! - -2b. Compile UNISIM/UNIMACRO libraries for ghdl ----------------------- - - A few entities use UNISIM or UNIMACRO primitives, and post synthesis models - require also UNISIM primitives. In these cases ghdl has to link against a - compiled UNISIM or UNIMACRO libraries. - - To make handling of the parallel installation of several Vivado versions - easy the compiled libraries are stored in sub-directories under $XTWV_PATH: - - $XTWV_PATH/ghdl/unisim - $XTWV_PATH/ghdl/unimacro - - A helper scripts will create these libraries: - - cd $RETROBASE - xviv_ghdl_unisim # does UNISIM and UNIMACRO - - Run these scripts for each Vivado version which is installed. - - Notes: - - Vivado supports SIMPRIM libraries only in Verilog form, there is no vhdl - version anymore. - - ghdl can therefore not be used to do timing simulations with Vivado. - However: under ISE SIMPRIM was available in vhdl, but ghdl did never accept - the sdf files, making ghdl timing simulations impossible under ISE too. - -3. Building test benches -------------------------------------------------- - - The build flows currently supports ghdl and the vivado simulator xsim. - -3a. With ghdl -------------------------------------------------------- - - To compile a ghdl based test bench named all is needed is - - make - - The make file will use .vbom, create all make dependency files, - and generate the needed ghdl commands. - - In some cases the test benches can also be compiled against the gate - level models derived after the synthesis or optimize step. - Vivado only generated functional (UNISIM based) models in vhdl. Timing - (SIMPRIM based) models are only available on verilog. The combination - vivado + ghdl is therefore limited to functional model simulation. - - To compile them - - make ghdl_tmp_clean - make _ssim # for post synthesis functional - make _osim # for post optimize functional - make _rsim # for post routing functional - - Individual working directories are used for the different models - ghdl.bsim for bahavioral model - ghdl.ssim for post synthesis - ghdl.osim for post optimize - ghdl.rsim for post routing - and can co-exist. The 'make ghdl_tmp_clean' can be used to flush the ghdl - work areas, but in general this is not needed (since V0.73). - - Notes: - - Many post-synthesis functional currently fail due to startup and - initialization problems (see issue V0.73-2). - -3b. With Vivado xsim ------------------------------------------------- - - To compile a Vivado xsim based test bench named all is needed is - - make _XSim - - The make file will use .vbom, create all make dependency files, - and generate the needed Vivado xsim project files and commands. - - In many cases the test benches can also be compiled against the gate - level models derived after the synthesis, optimize or routing step. - Vivado supports functional (UNISIM based) models in vhdl and in verilog, - and timing (SIMPRIM based) models only in verilog. Since practice showed - that verilog models compile and execute faster, verilog is used for both - functional and timing models. - - make _XSim_ssim # for post-synthesis functional - make _XSim_osim # for post-optimize functional - make _XSim_rsim # for post-routing functional - - make _XSim_esim # for post-synthesis timing - make _XSim_psim # for post-optimize timing - make _XSim_tsim # for post-routing timing - - Notes: - - as of vivado 2016.2 xelab shows sometimes extremely long build times, - especially for generated post-synthesis vhdl models (see issue V0.73-1). - - Many post-synthesis functional and especially post-routing timing - simulations currently fail due to startup and initialization problems - (see issue V0.73-2). - -4. Building systems ------------------------------------------------------- - - To generate a bit file for a system named all is needed is - - make .bit - - The make file will use .vbom, create all make dependency files and - starts Vivado in batch mode with the proper scripts which will handle the - build steps. The log files and reports are conveniently renamed - - _syn.log # synthesis log (from runme.log) - _imp.log # implementation log (from runme.log) - _bit.log # write_bitstream log (from runme.log) - - _syn_util.rpt # (from _utilization_synth.rpt) - _opt_drc.rpt # (from _opt_drc.rpt) - _pla_io.rpt # (from _io_placed.rpt) - _pla_clk.rpt # (from _clock_utilization_placed.rpt) - _pla_util.rpt # (from _utilization_placed.rpt) - _pla_cset.rpt # (from _control_sets_placed.rpt) - _rou_sta.rpt # (from _route_status.rpt) - _rou_drc.rpt # (from _drc_routed.rpt) - _rou_tim.rpt # (from _timing_summary_routed.rpt) - _rou_pwr.rpt # (from _power_routed.rpt) - _rou_util.rpt # (extra report_utilization) - _rou_util_h.rpt # (extra report_utilization -hierarchical) - _ds.rpt # (extra report_datasheet) - - The design check points are also kept - - _syn.dcp # (from .dcp) - _opt.dcp # (from _opt.dcp) - _pla.dcp # (from _placed.dcp) - _rou.dcp # (from _routed.dcp) - - If only the post synthesis, optimize or route design checkpoints are wanted - - make _syn.dcp - make _opt.dcp - make _rou.dcp - -5. Building vivado projects, creating gate level models ------------------- - - Vivado is used in 'project mode', whenever one of the targets mentioned - above is build a vivado project is freshly created in the directory - project_mflow - with the project file - project_mflow/project_mflow.xpr - - There are many make targets which - - just create the project - - start vivado in gui mode to inspect the most recent project - - create gate level models - - Specifically - - make .vivado # create vivado project from .vbom - make vivado # open project in project_mflow - - make _ssim.vhd # post-synthesis functional model (vhdl) - make _osim.vhd # post-optimize functional model (vhdl) - make _rsim.vhd # post-routing functional model (vhdl) - - make _ssim.v # post-synthesis functional model (verilog) - make _osim.v # post-optimize functional model (verilog) - make _rsim.v # post-routing functional model (verilog) - - make _esim.v # post-synthesis timing model (verilog) - make _psim.v # post-optimize timing model (verilog) - make _tsim.v # post-routing timing model (verilog) - - For timing model verilog file an associated sdf file is also generated. - -6. Configuring FPGAs ------------------------------------------------------ - - The make flow supports also loading the bitstream into FPGAs via the - Vivado hardware server. Simply use - - make .vconfig - - Note: works with Arty, Basys3, and Nexys4, only one board must connected. - -7. Note on ISE ------------------------------------------------------------ - - The development for Nexys4 started with ISE, but has now fully moved to - Vivado. The make files for the ISE build flows have been kept for comparison - are have the name Makefile.ise. So for some Nexys4 designs and associated - one can still start with a - - make -f Makefile.ise - or - makeise - - an ISE based build. To be used for tool comparisons, the ISE generated bit - files were never tested in an FPGA. diff --git a/doc/README_known_issues.md b/doc/README_known_issues.md new file mode 100644 index 00000000..f0b31b1a --- /dev/null +++ b/doc/README_known_issues.md @@ -0,0 +1,70 @@ +## Known issues +The case id indicates the release when the issue was first recognized. + +### V0.73-3 {[issue #11](https://github.com/wfjm/w11/issues/11)} +The 'state number generator' code in `pdp11_sequencer` causes in vivado +2016.1 (and .2) that the main FSM isn't re-coded anymore, which has high +impact on achievable clock rate. The two optional debug units depending on +the state number, dmscnt and dmcmon, are therefore currently deactivated in +all Artix based systems (but are available on all Spartan based systems). + +### V0.73-2 {[issue #10](https://github.com/wfjm/w11/issues/10)} +Many post-synthesis functional and especially post-routing timing +simulations currently fail due to startup and initialization problems. +Cause is MMCM/PLL startup, which is not properly reflected in the test +bench. Will be resolved in an upcoming release. + +### V0.73-1 {[issue #9](https://github.com/wfjm/w11/issues/9)} +as of vivado 2016.2 `xelab` shows sometimes extremely long build times, +especially for generated post-synthesis vhdl models. But also building a +behavioral simulation for a w11a design can take 25 min. Even though +post-synthesis or post-routing models are now generated in verilog working +with `xsim` is cumbersome and time consuming. + +### V0.66-1 {[issue #8](https://github.com/wfjm/w11/issues/8)} +the TM11 controller transfers data byte wise (all disk do it 16bit +word wise) and allows for odd byte length transfers. Odd length transfers +are currently not supported and rejected as invalid command. Odd byte +length records aren't used by OS, so in practice this limitation +isn't relevant. + +### V0.65-2 {[issue #7](https://github.com/wfjm/w11/issues/7)} +some exotic RH70/RP/RM features and conditions not implemented yet +- last block transfered flag (in DS) +- `CS2.BAI` currently ignored and not handled +- read or write 'with header' gives currently `ILF` + +All this isn't used by any OS, so in practice not relevant. + +### V0.65-1 {[issue #6](https://github.com/wfjm/w11/issues/6)} +`ti_rri` sometimes crashes in normal rundown (exit or ^D) when +a `cuff:` type rlink is active. One gets +``` + terminate called after throwing an instance of 'Retro::Rexception' + what(): RlinkPortCuff::Cleanup(): driver thread failed to stop +``` +Doesn't affect normal operation, will be fixed in upcoming release. + +### V0.64-6 {[issue #5](https://github.com/wfjm/w11/issues/5)} +IO delays still unconstraint in Vivado. All critical IOs use +explicitly IOB flops, thus timing well defined. + +### V0.64-2 {[issue #4](https://github.com/wfjm/w11/issues/4)} +rlink throughput on basys3/nexys4 limited by serial port stack +round trip times. Will be overcome by libusb based custom driver. + +### V0.64-1 {[issue #3](https://github.com/wfjm/w11/issues/3)} +The large default transfer size for disk accesses leads to bad +throughput in the DL11 emulation for low speed links, like the +460kBaud the S3board is limited to. Will be overcome by a DL11 +controller with more buffering. + +### V0.62-2 {[issue #2](https://github.com/wfjm/w11/issues/2)} +rlink v4 error recovery not yet implemented, will crash on error. + +### V0.62-1 {[issue #1](https://github.com/wfjm/w11/issues/1)} +rlink command lists aren't split to fit in retransmit buffer size. + +_{the last two issues are not relevant for w11 backend over USB usage because +the backend produces proper command lists and the USB channel is usually error +free}_ diff --git a/doc/README_known_issues.txt b/doc/README_known_issues.txt deleted file mode 100644 index 3dc969b7..00000000 --- a/doc/README_known_issues.txt +++ /dev/null @@ -1,51 +0,0 @@ -$Id: README_known_issues.txt 779 2016-06-26 15:37:16Z mueller $ - -Known issues for this release. -The case id indicates the release when the issue was first recognized. - -- V0.73-1: as of vivado 2016.2 xelab shows sometimes extremely long build times, - especially for generated post-synthesis vhdl models. But also building a - behavioral simulation for a w11a design can take 25 min. Even though - post-synthesis or post-routing models are now generated in verilog working - with xsim is cumbersome and time consuming. -- V0.73-2: Many post-synthesis functional and especially post-routing timing - simulations currently fail due to startup and initialization problems. - Cause is MMCM/PLL startup, which is not properly reflected in the test - bench. Will be resolved in an upcoming release. -- V0.73-3: The 'state number generator' code in pdp11_sequencer causes in vivado - 2016.1 (and .2) that the main FSM isn't re-coded anymore, which has high - impact on achievable clock rate. The two optional debug units depending on - the state number, dmscnt and dmcmon, are therefore currently deactivated in - all Artix based systems (but are available on all Spartan based systems). - -- V0.66-1: the TM11 controller transfers data byte wise (all disk do it 16bit - word wise) and allows for odd byte length transfers. Odd length transfers - are currently not supported and rejected as invalid command. Odd byte - length records aren't used by OS, if at all, so in practice this limitation - isn't relevant. - -- V0.65-1: ti_rri sometimes crashes in normal rundown (exit or ^D) when - a cuff: type rlink is active. One gets - terminate called after throwing an instance of 'Retro::Rexception' - what(): RlinkPortCuff::Cleanup(): driver thread failed to stop - doesn't affect normal operation, will be fixed in upcoming release. -- V0.65-2: some exotic RH70/RP/RM features and conditions not implemented yet - - last block transfered flag (in DS) - - CS2.BAI currently ignored and not handled - - read or write 'with header' gives currently ILF - All this isn't used by any OS, so in practice not relevant. - -- V0.64-6: IO delays still unconstraint in vivado. All critical IOs use - explicitly IOB flops, thus timing well defined. -- V0.64-2: rlink throughput on basys3/nexys4 limited by serial port stack - round trip times. Will be overcome by libusb based custom driver. -- V0.64-1: The large default transfer size for disk accesses leads to bad - throughput in the DL11 emulation for low speed links, like the - 460kBaud the S3board is limited too. Will be overcome by a DL11 - controller with more buffering. - -- V0.62-2: rlink v4 error recovery not yet implemented, will crash on error -- V0.62-1: Command lists aren't split to fit in retransmit buffer size - {last two issues not relevant for w11 backend over USB usage because - the backend produces proper command lists and the USB channel is - usually error free} diff --git a/doc/README_xadc.txt b/doc/README_xadc.md similarity index 93% rename from doc/README_xadc.txt rename to doc/README_xadc.md index 61e23727..b30f1b05 100644 --- a/doc/README_xadc.txt +++ b/doc/README_xadc.md @@ -1,10 +1,8 @@ -# $Id: README_xadc.txt 746 2016-03-19 13:08:36Z mueller $ - The Artix-7 based designs contain now a module which makes the data of the FPGA system monitor, called XADC in 7Series and SYSMON otherwise, available -on the rbus and therefore from ti_rri. +on the rbus and therefore from `ti_rri`. -To set this up in ti_rri or ti_w11 use +To set this up in `ti_rri` or `ti_w11` use package require rbsysmon rbsysmon::setup_xadc_arty; # for arty diff --git a/doc/w11a_known_issues.md b/doc/w11a_known_issues.md new file mode 100644 index 00000000..d7ca2996 --- /dev/null +++ b/doc/w11a_known_issues.md @@ -0,0 +1,95 @@ +# Summary of known issues for w11a CPU and systems + +###Table of content + +- [Known differences between w11a and KB11-C (11/70)](#user-content-diff) +- [Known limitations](#user-content-lim) +- [Known bugs](#user-content-bug) + +### Known differences between w11a and KB11-C (11/70) + +- the SPL instruction in the 11/70 always fetched the next instruction + regardless of pending device or even console interrupts. This is known + as the 'spl bug', see + - http://minnie.tuhs.org/pipermail/pups/2006-September/001082.html + - http://minnie.tuhs.org/pipermail/pups/2006-October/001083.html + + In the w11a the SPL has 11/70 semantics in kernel mode, thus next no + traps or interrupts, but in supervisor and user mode SPL really acts as + nop, so traps and interrupts are taken as for all other instructions. + **--> The w11a isn't bug compatible with the 11/70.** +- A 'red stack violation' looses PSW, a 0 is pushed in stack. +- The 'instruction complete flag' in SSR0 is not implemented, it is + permanently '0', SSR2 will not record vector addresses in case of a + vector fetch fault. Recovery of vector fetch faults is therefore not + possible, but only 11/45 and 11/70 supported this, no OS used that, and + it's even unclear whether it can be practically used. +- the 11/70 maps the 18 bit UNIBUS address space into the upper part of + the 22bit extended mode address space. With UNIBUS mapping enabled, this + allowed to access via 17000000:17757777 the memory exactly as a UNIBUS + device would see it. The w11a doesn't implement this remapping, an access + in the range 17000000:17757777 causes a NXM fault. + +All four points relate to very 11/70 specific behaviour, no operating system +depends on them, therefore they are considered acceptable implementation +differences + +### Known limitations + +- some programs use timing loops based on the execution speed of the + original processors. This can lead to spurious timeouts, especially + in old test programs. + **--> a 'CPU throttle mechanism' will be added in a future version to + circumvent this for some old test codes.** +- the emulated I/O can lead to apparently slow device reaction times, + especially when the server runs as normal user process. This can lead + to timeout, again mostly in test programs. + **--> a 'watch dog' mechanism will be added in a future version which + suspends the CPU when the server doesn't respond fast enough.** + +### Known bugs + +- **TCK-036 pri=L: RK11: hardware poll not working** +The RK11/RK05 hardware poll logic is probably not reflecting the +behaviour of the real drive. + +- **TCK-035 pri=L: RK11: no proper `NXM` check in 18bit systems** +No `NXM` error is generated when a RK11 read or write reaches the top +of memory in 18 bit addressing. Crash dump routines use this to detect +end-of-memory. + +- **TCK-032 pri=M: RK11: polling on `DRY` in `RKDS` doesn't work** +`DRY` in `RKDS` goes 1->0 immediately with `RDY` in `RKCS` when a function is +started. In a real RK05 drive `DRY` went to 0 after a short delay. Some +basic hardware tests are sensitive to this. + +- **TCK-030 pri=L: CPU: `SSR0` trap bit set when access aborted** +The 'trap bit' (bit 12: 10000) is set even when the access is aborted. + +- **TCK-029 pri=L: CPU: `AIB` `A` bit set for all accesses** +The MMU trap condition isn't properly decoded + +- **TCK-028 pri=H: CPU: interrupt and trap precedence** +In case of multiple trap, fault, or interrupt conditions the precedence +isn't implemented correctly. + +- **TCK-026 pri=L: CPU: src+dst delta added in `SSR1` when same register** +The `SSR1` content after a fault is logically correct in w11a, but +different from 11/70. + +- **TCK-025 pri=L: CPU: no mmu trap when bit9 clearing instruction traps** +In the 11/70 the instruction which affects mmu trap can cause a trap +already, in w11a only the next instruction will trap. + +- **TCK-014 pri=M: RK11: write protect action too slow** +Some simple RK11 drivers, especially in tests, don't poll for completion +of a write protect command. Due to the emulated I/O this can cause errors. + +- The last four issues are caused by an incorrect implementation of the trap +logic, which leads to a different precendence when multiple trap, fault, +or interrupt occur + - **TCK-007 pri=H: CPU: no trap-4 after emt on odd stack** + - **TCK-006 pri=H: CPU: no yel-stack trap after `jsr pc,nnn(pc)`** + - **TCK-004 pri=H: CPU: yel-stack by interrupt causes loop-up** + - **TCK-003 pri=H: CPU: yel-stack by iot pushes two stack frames** + diff --git a/doc/w11a_known_issues.txt b/doc/w11a_known_issues.txt deleted file mode 100644 index c7a4ca32..00000000 --- a/doc/w11a_known_issues.txt +++ /dev/null @@ -1,100 +0,0 @@ -# $Id: w11a_known_issues.txt 589 2014-08-30 12:43:16Z mueller $ - -Summary of known issues for w11a CPU and systems - - Table of content: - 1. Known differences between w11a and KB11-C (11/70) - 2. Known limitations - 3. Known bugs - - -1. Known differences between w11a and KB11-C (11/70) ---------------------- - - - the SPL instruction in the 11/70 always fetched the next instruction - regardless of pending device or even console interrupts. This is known - as the 'spl bug', see - http://minnie.tuhs.org/pipermail/pups/2006-September/001082.html - http://minnie.tuhs.org/pipermail/pups/2006-October/001083.html - In the w11a the SPL has 11/70 semantics in kernel mode, thus next no - traps or interrupts, but in supervisor and user mode SPL really acts as - nop, so traps and interrupts are taken as for all other instructions. - --> The w11a isn't bug compatible with the 11/70. - - - A 'red stack violation' looses PSW, a 0 is pushed in stack. - - - The 'instruction complete flag' in SSR0 is not implemented, it is - permanently '0', SSR2 will not record vector addresses in case of a - vector fetch fault. Recovery of vector fetch faults is therefore not - possible, but only 11/45 and 11/70 supported this, no OS used that, and - it's even unclear whether it can be practically used. - - - the 11/70 maps the 18 bit UNIBUS address space into the upper part of - the 22bit extended mode address space. With UNIBUS mapping enabled, this - allowed to access via 17000000:17757777 the memory exactly as a UNIBUS - device would see it. The w11a doesn't implement this remapping, an access - in the range 17000000:17757777 causes a NXM fault. - - All four points relate to very 11/70 specific behaviour, no operating system - depends on them, therefore they are considered acceptable implementation - differences - -2. Known limitations ------------------------------------------------------ - - - some programs use timing loops based on the execution speed of the - original processors. This can lead to spurious timeouts, especially - in old test programs. - --> a 'CPU throttle mechanism' will be added in a future version to - circumvent this for some old test codes. - - - the emulated I/O can lead to apparently slow device reaction times, - especially when the server runs as normal user process. This can lead - to timeout, again mostly in test programs. - --> a 'watch dog' mechanism will be added in a future version which - suspends the CPU when the server doesn't respond fast enough. - -3. Known bugs ------------------------------------------------------------- - - - TCK-036 pri=L: RK11: hardware poll not working - The RK11/RK05 hardware poll logic is probably no reflecting the - behaviour of the real drive. - - - TCK-035 pri=L: RK11: no proper NXM check in 18bit systems - No NXM error is generated when a RK11 read or write reaches the top - of memory in 18 bit addressing. Crash dump routines use this to detect - end-of-memory. - - - TCK-032 pri=M: RK11: polling on DRY in RKDS doesn't work - DRY in RKDS goes 1->0 immediately with RDY in RKCS when a function is - started. In a real RK05 drive DRY went to 0 after a short delay. Some - basic hardware tests are sensitive to this. - - - TCK-030 pri=L: CPU: SSR0 trap bit set when access aborted - The 'trap bit' (bit 12: 10000) is set even when the access is aborted. - - - TCK-029 pri=L: CPU: AIB A bit set for all accesses - The MMU trap condition isn't properly decoded - - - TCK-028 pri=H: CPU: interrupt and trap precedence - In case of multiple trap, fault, or interrupt conditions the precedence - isn't implemented correctly. - - - TCK-026 pri=L: CPU: src+dst delta added in ssr1 when same register - The ssr1 content after a fault is logically correct in w11a, but - different from 11/70. - - - TCK-025 pri=L: CPU: no mmu trap when bit9 clearing instruction traps - In the 11/70 the instruction which affects mmu trap can cause a trap - already, in w11a only the next instruction will trap. - - - TCK-014 pri=M: RK11: write protect action too slow - Some simple RK11 drivers, especially in tests, don't poll for completion - of a write protect command. Due to the emulated I/O this can cause errors. - - - TCK-007 pri=H: CPU: no trap-4 after emt on odd stack - - TCK-006 pri=H: CPU: no yel-stack trap after jsr pc,nnn(pc) - - TCK-004 pri=H: CPU: yel-stack by interrupt causes loop-up - - TCK-003 pri=H: CPU: yel-stack by iot pushes two stack frames - All four issues are caused by an incorrect implementation of the trap - logic, which leads to a different precendence when multiple trap, fault, - or interrupt occur. - diff --git a/doc/w11a_os_guide.md b/doc/w11a_os_guide.md new file mode 100644 index 00000000..9cb711ba --- /dev/null +++ b/doc/w11a_os_guide.md @@ -0,0 +1,289 @@ +# Guide to run operating system images on w11a systems + +### Table of content + +- [I/O emulation setup](#user-content-io-emu) +- [FPGA Board setup](#user-content-fpga-setup) +- [Rlink and Backend Server setup](#user-content-rlink) +- [simh simulator setup](#user-content-simh) +- [oskits](#user-content-oskits) + - [Unix systems](#user-content-oskits-unix) + - [DEC operating systems](#user-content-oskits-dec) + +### I/O emulation setup + +All UNIBUS peripherals which exchange data (currently DL11, LP11, PC11, RK11, +and RL11) are currently emulated via a backend process. The communication +between FPGA board and backend server can be via + +- Serial port + - via an integrated USB-UART bridge + - on arty, basys3, and nexys4 with a `FT2232HQ`, allows up to 12M Baud + - on nexys3 with a `FT232R`, allows up to 2M Baud + - via RS232 port, as on s3board and nexys2 + - using a serial port (/dev/ttySx) is limited to 115 kBaud on most PCs. + - using a USB-RS232 adapter was tested up to 460k Baud. + +- Direct USB connection using a Cypress FX2 USB controller + - is supported on the nexys2 and nexys3 FPGA boards + - much faster than serial port connections (see below) + - also allows to configure the FPGA over the same USB connection + +- Notes: + - A 10M Baud connection, like on a nexys4, gives disk access rates and + throughputs much better than the real hardware of the 70's and is well + suitable for practical usage. + - In an OS with good disk caching like 2.11BSD the impact of disk speed + is actually smaller than the bare numbers suggest. + - A 460k Baud connection gives in practice a disk throughput of ~20 kB/s. + This allows to test the system but is a bit slow for real usage. + - USB-RS232 cables with a FTDI `FT232R` chip work fine, tests with Prolific + Technology `PL2303` based cable never gave reliable connections for higher + Baud rates. + +Recommended setup for best performance (boards ordered by vintage): + +| Board | Channel/Interface | nom. speed | peak transfer rate | +| :---- | :---------------- | :--------- | -----------------: | +| arty | USB-UART bridge | 10M Baud | 910 kB/sec | +| basys3 | USB-UART bridge | 10M Baud | 910 kB/sec | +| nexys4 | USB-UART bridge | 10M Baud | 910 kb/sec | +| nexys3 | Cypress FX2 USB | USB2.0 speed | 30000 kB/sec | +| nexys3 | Cypress FX2 USB | USB2.0 speed | 30000 kB/sec | +| s3board | RS232+USB-RS232 cable | 460k Baud | 41 kB/sec | + +### FPGA Board setup + +Recommended setups + +- Arty + - connect USB cable to micro-USB connector labeled 'J10' + - to configure via vivado hardware server + + make .vconfig + + +- Basys3 + - connect USB cable to micro-USB connector labeled 'PROG' + - to configure via vivado hardware server + + make .vconfig + + +- Nexys4 + - connect USB cable to micro-USB connector labeled 'PROG' + - to configure via vivado hardware server + + make .vconfig + +- Nexys3 + - use Cypress FX for configure and and rlink communication + - connect USB cable to micro-USB connector labeled 'USB PROG' + - to configure via FX2 and jtag tool + + make .jconfig + +- Nexys2 + - connect USB cable to mini-USB connector (between RS232 and PS/2 port) + - to configure via FX2 and jtag tool + + make .jconfig + +- S3board + - connect the USB-RS232 cable to the RS232 port + - connect a JTAG programmer (e.g. Xilinx USB Cable II) to JTAG pins + - to configure via ISE Impact + + make .iconfig + +### Rlink and Backend Server setup + +All examples below use the same basic setup + +- setup `vt100` emulator windows + + cd $RETROBASE/tools/oskit/ + console_starter -d DL0 & + console_starter -d DL1 & + +- setup rlink connection using `ti_rri` backend server via the `ti_w11` + quick start wrapper script. Ensure that all 8 switches on the board + are in the indicated positions (SWI=...). The concrete boot script + name is given in the following sections + + - for arty over serial + + SWI = 0110 (gives console light emulation...) + ti_w11 -tu,12M,break,xon @_boot.tcl + + **Note**: the arty w11a has currently only 176 kB memory (all from BRAMS!) + unix-v5 works fine. XXDP, RT11 and RSX-11M should work. + 211bsd will not boot, either most RSX-11M+ systems. + + - for b3 over serial + + SWI = 00000000 00101000 (gives console light display on LEDS) + ti_w11 -tu,12M,break,xon @_boot.tcl + + + **Note**: the basys3 w11a has only 176 kB memory (all from BRAMS!) + unix-v5 works fine. XXDP, RT11 and RSX-11M should work. + 211bsd will not boot, either most RSX-11M+ systems. + + - for n4 over serial + + SWI = 00000000 00101000 (gives console light display on LEDS) + ti_w11 -tu,12M,break,cts @_boot.tcl + + - for n2,n3 over fx2 + + SWI = 00101100 + ti_w11 -u @_boot.tcl + + - for s3 serial + + SWI = 00101010 + ti_w11 -tu,460k,break,xon @_boot.tcl + + Notes: + - on ``, the serial device number + - check with `ls /dev/ttyUSB*` to see what is available + - `` is typically '1' if a single `FT2232HQ` based boardis connected, + like a arty, basys3, or nexys4. Initially two ttyUSB devices show up, + the lower is for FPGA config and will disappear when Vivado hardware + server is used once. The upper provides the data connection. + - `` is typically '0' if only a single USB-RS232 cable is connected + + - on LED display + - is controlled by SWI(3) + + 0 -> system status + 1 -> DR emulation --> OS specific light patterns + + - on Hex display + - is controlled by SWI(5:4) + - boards with a 4 digit display + + 00 -> serial link rate divider + 01 -> PC + 10 -> DISPREG + 11 -> DR emulation + + - boards with 8 digit display + + SWI(5) select for DSP(7:4) display + 0 -> serial link rate divider + 1 -> PC + SWI(4) select for DSP(3:0) display + 0 -> DISPREG + 1 -> DR emulation + +### simh simulator setup + +Sometimes it is good to compare the w11a behavior with the PDP-11 software +emulator from the simh project (see http://simh.trailing-edge.com/). + +Under `$RETROBASE/tools/simh` two setup files are provided with configure +simh to reflect the w11a setup as close as possible: +- `setup_w11a_min.scmd` + Very close the current w11a state when it runs on an s3board + - processor: 11/70, no FPP, 1 Mbyte + - periphery: 2 DL11, LP11, RK11, PC11 +- `setup_w11a_max.scmd` + Planned configuration for the w11a, in addition + - processor: 4 Mbyte memory (as on Nexys2, Nexys3,...) + - periphery: DZ11, RL11/RL02, RK70/RP06, TM11/TU10 + +Startup scripts are provided with each oskit. They call the w11a_max +configuration, so will show in the emulator what w11a can do when +finished. + +All examples below use the same basic setup +- setup vt100 emulator window for 2nd DL11 + + cd $RETROBASE/tools/oskit/ + console_starter -s -d DL1 & + + **Note**: the -s ensures that the port numbers used by simh are taken! + +- start the simulator + + pdp11 _boot.scmd + +###oskits + +Ready to be used 'oskits' are provided under + + $RETROBASE/tools/oskit/ + +The tarballs with the disk images are provided from a web server +and have to be installed separately. + +###Unix systems + +#### Legal and license issues + +Ancient UNIX systems for the PDP-11 can now be freely used under the +'Caldera license'. 2.11BSD was released 1992 under the 4 clause BSD +license. Taken together + +- Unix V1 to V7 +- all BSD Unix versions for PDP-11 + +can be freely distributed and used for non-commercial purposes. + +Several oskits are provided: + +| oskit Name | OS | Disk/Tape| Comment | +| :---- | :----| :------ | :------ | +| unix-v5_rk | Unix V5 System | RK05 | | +| 211bsd_rk | 2.11BSD system | RK05 | _very elementary subset_ | +| 211bsd_rl | 2.11BSD system | RL02 | _small subset_ | +| 211bsd_rp | 2.11BSD system | RP06 | _full system_ | + +For further details consult the `README_set.txt` file in the +oskit directory. + +### DEC operating systems + +#### Legal and license issues + +Unfortunately there is no general hobbyist license for DEC operating +systems for PDP-11 computers. The 'Mentec license' is commonly understood +to cover the some older versions of DEC operating systems, for example + +- RT-11 V5.3 or prior +- RSX-11M V4.3 or prior +- RSX-11M PLUS V3.0 or prior + +on a simulator. It is commonly assumed that the license terms cover the +usage of the PDP11 simulator from the 'simh' suite. Usage of the e11 +simulator is not covered according to the author of e11. + +> **THIS LICENSE DOES NOT COVER THE USAGE OF THESE HISTORIC DEC** +> **OPERATING SYSTEMS ON ANY 'REAL HARDWARE' IMPLEMENTATION OF A** +> **PDP-11. SO USAGE ON THE W11 IS *NOT* COVERED BY THE 'Mentec-license'.** + +Some oskits are provided with systems sysgen'ed to run on a configuration +like the w11a. + +- Feel free to explore them with the simh simulator. + The boot scripts for simh are included ( `.simh` ) + +- In case you happen to have a valid license feel free to try them + out the W11A and let the author know whether is works as it should. + For convenience the boot scripts are also included ( `.tcl` ). + +Several oskits are provided: + +| oskit Name | OS | Disk/Tape| Comment | +| :---- | :----| :------ | :------ | +| rsx11m-31_rk | RSX-11M V3.1 | RK05 | | +| rsx11m-40_rk | RSX-11M V4.0 | RK05 | | +| rsx11mp-30_rp | RSX-11M+ V3.0 | RP06 | | +| rt11-40_rk | RT-11 V4.0 | RK05 | | +| rt11-53_rl | RT-11 V5.3 | RL02 | | +| xxdp_rl | XXDP 22 and 25 | RL02 | | + +For further details consult the `README_set.txt` file in the +oskit directory. diff --git a/doc/w11a_os_guide.txt b/doc/w11a_os_guide.txt deleted file mode 100644 index 2f05768c..00000000 --- a/doc/w11a_os_guide.txt +++ /dev/null @@ -1,272 +0,0 @@ -# $Id: w11a_os_guide.txt 779 2016-06-26 15:37:16Z mueller $ - -Guide to run operating system images on w11a systems - - Table of content: - - 1. I/O emulation setup - 2. FPGA Board setup - 3. Rlink and Backend Server setup - 4. simh simulator setup - 5. oskits - a. Unix systems - b. DEC operating systems - -1. I/O emulation setup ---------------------------------------------------- - - All UNIBUS peripherals which exchange data (currently DL11, LP11, PC11, RK11, - and RL11) are currently emulated via a backend process. The communication - between FPGA board and backend server can be via - - - Serial port - - via an integrated USB-UART bridge - - on arty, basys3, and nexys4 with a FT2232HQ, allows up to 12M Baud - - on nexys3 with a FT232R, allows up to 2M Baud - - via RS232 port, as on s3board and nexys2 - - using a serial port (/dev/ttySx) is limited to 115 kBaud on most PCs. - - using a USB-RS232 adapter was tested up to 460k Baud. - - - Direct USB connection using a Cypress FX2 USB controller - - is supported on the nexys2 and nexys3 FPGA boards - - much faster than serial port connections (see below) - - also allows to configure the FPGA over the same USB connection - - Notes: - - A 10M Baud connection, like on a nexys4, gives disk access rates and - throughputs much better than the real hardware of the 70's and is well - suitable for practical usage. - - In an OS with good disk caching like 2.11BSD the impact of disk speed - is actually smaller than the bare numbers suggest. - - A 460k Baud connection gives in practice a disk throughput of ~20 kB/s. - This allows to test the system but is a bit slow for real usage. - - USB-RS232 cables with a FTDI FT232R chip work fine, tests with Prolific - Technology PL2303 based cable never gave reliable connections for higher - Baud rates. - - Recommended setup for best performance (boards ordered by vintage): - - Board Channel/Interface nom. speed peak transfer rate - - arty USB-UART bridge 10M Baud 910 kB/sec - basys3 USB-UART bridge 10M Baud 910 kB/sec - nexys4 USB-UART bridge 10M Baud 910 kb/sec - nexys3 Cypress FX2 USB USB2.0 speed 30000 kB/sec - nexys2 Cypress FX2 USB USB2.0 speed 30000 kB/sec - s3board RS232+USB-RS232 cable 460k Baud 41 kB/sec - -2. FPGA Board setup ------------------------------------------------------- - - Recommended setups - - - Arty - - connect USB cable to micro-USB connector labeled 'J10' - - to configure via vivado hardware server - make .vconfig - - - Basys3 - - connect USB cable to micro-USB connector labeled 'PROG' - - to configure via vivado hardware server - make .vconfig - - - Nexys4 - - connect USB cable to micro-USB connector labeled 'PROG' - - to configure via vivado hardware server - make .vconfig - - - Nexys3 - - use Cypress FX for configure and and rlink communication - - connect USB cable to micro-USB connector labeled 'USB PROG' - - to configure via FX2 and jtag tool - make .jconfig - - - Nexys2 - - connect USB cable to mini-USB connector (between RS232 and PS/2 port) - - to configure via FX2 and jtag tool - make .jconfig - - - S3board - - connect the USB-RS232 cable to the RS232 port - - connect a JTAG programmer (e.g. Xilinx USB Cable II) to JTAG pins - - to configure via ISE Impact - make .iconfig - -3. Rlink and Backend Server setup ----------------------------------------- - - All examples below use the same basic setup - - - setup vt100 emulator windows - - cd $RETROBASE/tools/oskit/ - console_starter -d DL0 & - console_starter -d DL1 & - - - setup rlink connection using ti_rri backend server via the ti_w11 - quick start wrapper script. Ensure that all 8 switches on the board - are in the indicated positions (SWI=...). The concrete boot script - name is given in the following sections - - - for arty over serial - SWI = 0110 (gives console light emulation...) - ti_w11 -tu,12M,break,xon @_boot.tcl - - NOTE: the arty w11a has currently only 176 kB memory (all from BRAMS!) - unix-v5 works fine. XXDP, RT11 and RSX-11M should work. - 211bsd will not boot, either most RSX-11M+ systems. - - - for b3 over serial - SWI = 00000000 00101000 (gives console light display on LEDS) - ti_w11 -tu,12M,break,xon @_boot.tcl - - NOTE: the basys3 w11a has only 176 kB memory (all from BRAMS!) - unix-v5 works fine. XXDP, RT11 and RSX-11M should work. - 211bsd will not boot, either most RSX-11M+ systems. - - - for n4 over serial - SWI = 00000000 00101000 (gives console light display on LEDS) - ti_w11 -tu,12M,break,cts @_boot.tcl - - - for n2,n3 over fx2 - SWI = 00101100 - ti_w11 -u @_boot.tcl - - - for s3 serial - SWI = 00101010 - ti_w11 -tu,460k,break,xon @_boot.tcl - - Notes: - - on , the serial device number - - check with 'ls /dev/ttyUSB*' to see what is available - - is typically '1' if a single FT2232HQ based boardis connected, - like a arty, basys3, or nexys4. Initially two ttyUSB devices show up, - the lower is for FPGA config and will disappear when Vivado hardware - server is used once. The upper provides the data connection. - - is typically '0' if only a single USB-RS232 cable is connected - - - on LED display - - is controlled by SWI(3) - 0 -> system status - 1 -> DR emulation --> OS specific light patterns - - - on Hex display - - is controlled by SWI(5:4) - - boards with a 4 digit display - 00 -> serial link rate divider - 01 -> PC - 10 -> DISPREG - 11 -> DR emulation - - boards with 8 digit display - - SWI(5) select for DSP(7:4) display - 0 -> serial link rate divider - 1 -> PC - - SWI(4) select for DSP(3:0) display - 0 -> DISPREG - 1 -> DR emulation - -4. simh simulator setup --------------------------------------------------- - - Sometimes it is good to compare the w11a behavior with the PDP-11 software - emulator from the simh project (see http://simh.trailing-edge.com/). - - Under $RETROBASE/tools/simh two setup files are provided with configure - simh to reflect the w11a setup as close as possible: - - setup_w11a_min.scmd - Very close the current w11a state when it runs on an s3board - - processor: 11/70, no FPP, 1 Mbyte - - periphery: 2 DL11, LP11, RK11, PC11 - - setup_w11a_max.scmd - Planned configuration for the w11a, in addition - - processor: 4 Mbyte memory (as on Nexys2, Nexys3,...) - - periphery: DZ11, RL11/RL02, RK70/RP06, TM11/TU10 - - Startup scripts are provided with each oskit. They call the w11a_max - configuration, so will show in the emulator what w11a can do when - finished. - - All examples below use the same basic setup - - - setup vt100 emulator window for 2nd DL11 - - cd $RETROBASE/tools/oskit/ - console_starter -s -d DL1 & - - {Note: the -s ensures that the port numbers used by simh are taken!} - - - start the simulator - - pdp11 _boot.scmd - -5. oskits ----------------------------------------------------------------- - - Ready to be used 'oskits' are provided under - $RETROBASE/tools/oskit/ - - The tarballs with the disk images are provided from a web server - and have to be installed separately. - -5a. Unix systems ----------------------------------------------------- - - Legal and license issues: - - Ancient UNIX systems for the PDP-11 can now be freely used under the - 'Caldera license'. 2.11BSD was released 1992 under the 4 clause BSD - license. Taken together - - - Unix V1 to V7 - - all BSD Unix versions for PDP-11 - - can be freely distributed and used for non-commercial purposes. - - Several oskits are provided: - - - unix-v5_rk: Unix V5 System on RK05 - - - 211bsd_rk: 2.11BSD system on RK05 (very elementary subset) - - 211bsd_rl: 2.11BSD system on RL02 (small subset) - - 211bsd_rp: 2.11BSD system on RP06 (full system) - - For further details consult the README_set.txt file in the - oskit directory. - -5b. DEC operating systems -------------------------------------------- - - Legal and license issues: - - Unfortunately there is no general hobbyist license for DEC operating - systems for PDP-11 computers. The 'Mentec license' is commonly understood - to cover the some older versions of DEC operating systems, for example - - RT-11 V5.3 or prior - - RSX-11M V4.3 or prior - - RSX-11M PLUS V3.0 or prior - on a simulator. It is commonly assumed that the license terms cover the - usage of the PDP11 simulator from the 'simh' suite. Usage of the e11 - simulator is not covered according to the author of e11. - - HOWEVER: THIS LICENSE DOES NOT COVER THE USAGE OF THESE HISTORIC DEC - OPERATING SYSTEMS ON ANY 'REAL HARDWARE' IMPLEMENTATION OF A - PDP-11. SO USAGE ON THE W11 IS *NOT* COVERED BY THE - 'Mentec-license'. - - Some oskits are provided with systems sysgen'ed to run on a configuration - like the w11a. - - - Feel free to explore them with the simh simulator. - The boot scripts for simh are included ( .simh ) - - - In case you happen to have a valid license feel free to try them - out the W11A and let the author know whether is works as it should. - For convenience the boot scripts are also included ( .tcl ). - - Several oskits are provided: - - - rsx11m-31_rk: RSX-11M V3.1 on RK05 - - rsx11m-40_rk: RSX-11M V4.0 on RK05 - - - rsx11mp-30_rp: RSX-11M+ V3.0 on RP06 - - - rt11-40_rk: RT-11 V4.0 on RK05 - - rt11-53_rl: RT-11 V5.3 on RL02 - - - xxdp_rl: XXDP 22 and 25 on RL02 - - For further details consult the README_set.txt file in the - oskit directory. diff --git a/doc/w11a_seq_flow.md b/doc/w11a_seq_flow.md new file mode 100644 index 00000000..f4b96055 --- /dev/null +++ b/doc/w11a_seq_flow.md @@ -0,0 +1,30 @@ +# w11a State Diagram Annotation + +The states are + 1. grouped by _flows_, related states are in a dashed box + 2. grouped in _classes_ by color + +| Color | State Class | +| :---- | :---------- | +| blue | idle/fetch/decode states | +| cyan | console handling states | +| light orange | source address mode flow | +| dark orange | destination address mode flows | +| green | states for main opcode handling | +| red | states for error handling | + +The grey `fork_...` hexagons represent three transition groups which are +common to the control flow of several states. There is no corresponding +state, these symbols just help to reduce the number of transition lines +on the flow chart. + +The transitions are color coded too: + +| Color | Transition Class | +| :---- | :--------------- | +| green | normal _forward_ transition in a flow | +| blue | i/o wait loop | +| red | error/trap handling | +| magenta | fatal errors to cpufail state | +| thick black | link to a `fork_...` symbol | +| black | all other transitions | diff --git a/doc/w11a_seq_flow.txt b/doc/w11a_seq_flow.txt deleted file mode 100644 index f29c6e8a..00000000 --- a/doc/w11a_seq_flow.txt +++ /dev/null @@ -1,24 +0,0 @@ -# $Id: w11a_seq_flow.txt 317 2010-07-22 19:36:56Z mueller $ - -The states are - 1. grouped by 'flows', related states are in a dashed box - 2. grouped in classes by color - - blue: idle/fetch/decode states - - cyan: console handling states - - light orange: source address mode flow - - dark orange: destination address mode flows - - green: states for main opcode handling - - red: states for error handling - -The grey 'fork_...' hexagons represent three transition groups which are -common to the control flow of several states. There is no corresponding -state, these symbols just help to reduce the number of transition lines -on the flow chart. - -The transitions are color coded too: - - green: normal 'forward' transition in a flow - - blue: i/o wait loop - - red: error/trap handling - - magenta: fatal errors to cpufail state - - thick black: link to a fork_ symbol - - black: all other transitions diff --git a/doc/w11a_tb_guide.md b/doc/w11a_tb_guide.md new file mode 100644 index 00000000..137de0cb --- /dev/null +++ b/doc/w11a_tb_guide.md @@ -0,0 +1,182 @@ +# Guide to running test benches + +### Table of content + +- [Tests bench environment](#user-content-env) +- [Unit test benches](#user-content-tb-unit) +- [System test benches](#user-content-tb-sys) +- [Test bench driver](#user-content-tb-driver) +- [Execute all available tests](#user-content-tb-exec) +- [Available unit test benches](#user-content-list-tb-unit) +- [Available system test benches](#user-content-list-tb-sys) + +### General Notes +- Ghdl is used for all behavioral simulations +- Optionally Vivado xsim can be used +- For post synthesis or post implementation functionnal simulations + either Ghdl or Vivado xsim can be used. +- For timing simulations only Vivado xsim can be used. +- ISE isim is also available, but considered legacy support + +### Tests bench environment + +All test benches have the same simple structure: + +- the test benches are 'self-checking'. For unit tests a stimulus process + reads test patterns as well as the expected responses from a stimulus file + +- the responses are checked in very simple cases by the stimulus process, + in general by a monitoring process + +- the test bench produces a comprehensive log file. For each checked + response the line contains the word "CHECK" and either an "OK" or a + "FAIL", in the later case in general with an indication of whats wrong. + Other unexpected behaviour, like timeouts, will also result in a line + containing the word "FAIL". + +- at the end a line with the word "DONE" is printed. + +- Most tests can be run as + + | Name | Model Type | Sub Type | + | :--- | :--------- | :------- | + | bsim | behavioral model | | + | ssim | post-synthesis | functional | + | osim | post-optimization | functional | + | rsim | post-routing | functional | + | esim | post-synthesis | timing | + | psim | post-optimization | timing | + | tsim | post-routing | timing | + + Building the simulation models is handled by the build environment. See + [README_buildsystem_Vivado.md](README_buildsystem_Vivado.md) for details + of the vivado flow and + [README_buildsystem_ISE.md](README_buildsystem_ISE.md) for the ISE flow. + +### Unit test benches + +All unit test are executed via `tbw` (test bench warpper) script. + +- the test bench is run like + + tbw [stimfile] | tbfilt --tee + + where + - tbw sets up the environment of the test bench and starts it. + It generates required symbolic links, e.g. to the stimulus file, + the defaults extracted from the file tbw.dat, if an optional file + name is give this one will be used instead. + - tbfilt saves the full test bench output to a logfile and filters + the output for PASS/FAIL criteria + +- for convenience a wrapper script `tbrun_tbw` is used to generate the + tbw|tbfilt pipe. This script also checks with `make` whether the + test bench is up-to-date or must be (re)-compiled. + +### System test benches + +The system tests allow to verify to verify a full system design. +In this case vhdl test bench code contains +- (simple) models of the memories used on the FPGA boards +- drivers for the rlink connection (currently just serialport) +- code to interface the rlink data stream to a UNIX 'named pipe', + implemented with a C routine which is called via VHPI from VHDL. + +This way the whole ghdl simulation can be controlled via a di-directional +byte stream. + +The rlink backend process can connect either via a named pipe to a ghdl +simulation, or via a serial port to a FPGA board. This way the same tests +can be executed in simulation and on real hardware. + +In general the script `tbrun_tbwrri` is used to generate the quite lengthy +command to properly setup the tbw|tbfilt pipe. This script also checks +with `make` whether the test bench is up-to-date or must be (re)-compiled. + +### Test bench driver + +All available tests (unit and system test benches) are described in a +set of descriptor files, usually called `tbrun.yml`. The top level file +in `$RETROBASE` includes other descriptor files located in the source +directories of the tests. + +The script `tbrun` reads these descriptor files, selects tests based +on `--tag` and `--exclude` options, and executes the tests with the +simulation engine and simulation type given by the `--mode` option. +For full description of see `man tbrun`. + +The low level drivers `tbrun_tbw` and `tbrun_tbwrri` will automatically +build the model if it is not available or outdated. This is very convenient +when working with a single test bench during development. + +When executing a large number of them it's in general better to separate +the model building (make phase) made model execution (run phase). Both +the low level drivers as well as `tbrun` support this via the options +`--nomake` and `--norun`. + +The individial test benches are simplest started via tbrun and a proper +selection via `--tag`. Very helpful is + + cd $RETROBASE + tbrun --dry --tag=.* + +which gives a listing of all available test. The tag list as well as +the shell commands to execute the test are shown. + +### Execute all available tests + +As stated above it is in general better to to separate the model building +(make phase) made model execution (run phase). The currently recommended +way to execute all test benches is given below. +The run time is measured on a 3 GHz dual core system. + + cd $RETROBASE + # build all behavioral models + # first all with ISE work flow + time nice tbrun -j 2 -norun -tag=ise -tee=tbrun_make_ise_bsim.log + # --> real 3m41.732s user 6m3.381s sys 0m24.224s + + # than all with vivado work flow + time nice tbrun -j 2 -norun -tag=viv -tee=tbrun_make_viv_bsim.log + # --> real 3m36.532s user 5m58.319s sys 0m25.235s + + # than execute all behavioral models + time nice tbrun -j 2 -nomake -tag=ise -tee=tbrun_run_ise_bsim.log + # --> real 3m19.799s user 5m45.060s sys 0m6.625s + time nice tbrun -j 2 -nomake -tag=viv -tee=tbrun_run_viv_bsim.log + #--> real 3m49.193s user 5m44.063s sys 0m5.332s + +All test create an individual logfile. `tbfilt` can be used to scan +these logfiles and create a summary with + + tbfilt -all -sum -comp + +It should look like + + 76m 0m00.034s c 0.92u 0 PASS tb_is61lv25616al_bsim.log + 76m 0m00.153s c 4.00u 0 PASS tb_mt45w8mw16b_bsim.log + 76m 0m00.168s c 1146 0 PASS tb_nx_cram_memctl_as_bsim.log + ... + ... + 76m 0m03.729s c 61258 0 PASS tb_pdp11core_bsim_base.log + 76m 0m00.083s c 1121 0 PASS tb_pdp11core_bsim_ubmap.log + 76m 0m00.068s c 1031 0 PASS tb_rlink_tba_pdp11core_bsim_ibdr.log + +### Available unit test benches + + tbrun --tag=comlib # comlib unit tests + tbrun --tag=serport # serport unit tests + tbrun --tag=rlink # rlink unit tests + tbrun --tag=issi # SRAM model unit tests + tbrun --tag=micron # CRAM model unit tests + tbrun --tag=sram_memctl # SRAM controller unit tests + tbrun --tag=cram_memctl # CRAM controller unit tests + tbrun --tag=w11a # w11a unit tests + +### Available system test benches + + tbrun --tag=sys_tst_serloop.* # all sys_tst_serloop designs + tbrun --tag=sys_tst_rlink # all sys_tst_rlink designs + tbrun --tag=sys_tst_rlink_cuff # all sys_tst_rlink_cuff designs + tbrun --tag=sys_tst_sram # all sys_tst_sram designs + tbrun --tag=sys_w11a # all w11a designs diff --git a/doc/w11a_tb_guide.txt b/doc/w11a_tb_guide.txt deleted file mode 100644 index 5801431e..00000000 --- a/doc/w11a_tb_guide.txt +++ /dev/null @@ -1,178 +0,0 @@ -# $Id: w11a_tb_guide.txt 810 2016-10-02 16:51:12Z mueller $ - -Note: - Ghdl is used for all behavioral simulations - - Optionally Vivado xsim can be used - - For post synthesis or post implementation functionnal simulations - either Ghdl or Vivado xsim can be used. - - For timing simulations only Vivado xsim can be used. - - ISE isim is also available, but considered legacy support - -Guide to running test benches - - Table of content: - - 1. Tests bench environment - 2. Unit test benches - 3. System test benches - 4. Test bench driver - 5. Execute all available tests - 6. Available unit tests benches - 7. Available system tests benches - - -1. Tests bench environment ------------------------------------------------ - - All test benches have the same simple structure: - - - the test benches are 'self-checking'. For unit tests a stimulus process - reads test patterns as well as the expected responses from a stimulus file - - - the responses are checked in very simple cases by the stimulus process, - in general by a monitoring process - - - the test bench produces a comprehensive log file. For each checked - response the line contains the word "CHECK" and either an "OK" or a - "FAIL", in the later case in general with an indication of whats wrong. - Other unexpected behaviour, like timeouts, will also result in a line - containing the word "FAIL". - - - at the end a line with the word "DONE" is printed. - - - Most tests can be run as - - bsim: the behavioral model - - ssim: post-synthesis functional - - osim: post-optimization functional - - rsim: post-routing functional - - esim: post-synthesis timing - - psim: post-optimization timing - - tsim: post-routing timing - - Building the simulation models is handled by the build environment. See - README_buildsystem_Vivado.txt for details of the vivado flow and - README_buildsystem_ISE.txt for the ISE flow. - -2. Unit test benches ------------------------------------------------------ - - All unit test are executed via 'tbw' (test bench warpper) script. - - - the test bench is run like - - tbw [stimfile] | tbfilt --tee - - where - - tbw sets up the environment of the test bench and starts it. - It generates required symbolic links, e.g. to the stimulus file, - the defaults extracted from the file tbw.dat, if an optional file - name is give this one will be used instead. - - tbfilt saves the full test bench output to a logfile and filters - the output for PASS/FAIL criteria - - - for convenience a wrapper script 'tbrun_tbw' is used to generate the - tbw|tbfilt pipe. This script also checks with 'make' whether the - test bench is up-to-date or must be (re)-compiled. - -3. System test benches ---------------------------------------------------- - - The system tests allow to verify to verify a full system design. - In this case vhdl test bench code contains - - (simple) models of the memories used on the FPGA boards - - drivers for the rlink connection (currently just serialport) - - code to interface the rlink data stream to a UNIX 'named pipe', - implemented with a C routine which is called via VHPI from VHDL. - This way the whole ghdl simulation can be controlled via a di-directional - byte stream. - - The rlink backend process can connect either via a named pipe to a ghdl - simulation, or via a serial port to a FPGA board. This way the same tests - can be executed in simulation and on real hardware. - - In general the script 'tbrun_tbwrri' is used to generate the quite lengthy - ommand to properly setup the tbw|tbfilt pipe. This script also checks - with 'make' whether the test bench is up-to-date or must be (re)-compiled. - -4. Test bench driver ------------------------------------------------------ - - All available tests (unit and system test benches) are described in a - set of descriptor files, usually called 'tbrun.yml'. The top level file - in $RETROBASE includes other descriptor files located in the source - directories of the tests. - - The script 'tbrun' reads these descriptor files, selects tests based - on --tag and --exclude options, and executes the tests with the - simulation engine and simulation type given by the --mode option. - For full description of see 'man tbrun'. - - The low level drivers 'tbrun_tbw' and 'tbrun_tbwrri' will automatically - build the model if it is not available or outdated. This is very convenient - when working with a single test bench during development. - - When executing a large number of them it's in general better to separate - the model building (make phase) made model execution (run phase). Both - the low level drivers as well as 'tbrun' support this via the options - --nomake and --norun. - - The individial test benches are simplest started via tbrun and a proper - selection via --tag. Very helpful is - - cd $RETROBASE - tbrun --dry --tag=.* - - which gives a listing of all available test. The tag list as well as - the shell commands to execute the test are shown. - -5. Execute all available tests -------------------------------------------- - - As stated above it is in general better to to separate the model building - (make phase) made model execution (run phase). The currently recommended - way to execute all test benches is given below. - The run time is measured on a 3 GHz dual core system. - - cd $RETROBASE - # build all behavioral models - # first all with ISE work flow - time nice tbrun -j 2 -norun -tag=ise -tee=tbrun_make_ise_bsim.log - # --> real 3m41.732s user 6m3.381s sys 0m24.224s - - # than all with vivado work flow - time nice tbrun -j 2 -norun -tag=viv -tee=tbrun_make_viv_bsim.log - # --> real 3m36.532s user 5m58.319s sys 0m25.235s - - # than execute all behavioral models - time nice tbrun -j 2 -nomake -tag=ise -tee=tbrun_run_ise_bsim.log - # --> real 3m19.799s user 5m45.060s sys 0m6.625s - time nice tbrun -j 2 -nomake -tag=viv -tee=tbrun_run_viv_bsim.log - #--> real 3m49.193s user 5m44.063s sys 0m5.332s - - All test create an individual logfile. 'tbfilt' can be used to scan - these logfiles and create a summary with - - tbfilt -all -sum -comp - - It should look like - 76m 0m00.034s c 0.92u 0 PASS tb_is61lv25616al_bsim.log - 76m 0m00.153s c 4.00u 0 PASS tb_mt45w8mw16b_bsim.log - 76m 0m00.168s c 1146 0 PASS tb_nx_cram_memctl_as_bsim.log - ... - ... - 76m 0m03.729s c 61258 0 PASS tb_pdp11core_bsim_base.log - 76m 0m00.083s c 1121 0 PASS tb_pdp11core_bsim_ubmap.log - 76m 0m00.068s c 1031 0 PASS tb_rlink_tba_pdp11core_bsim_ibdr.log - -6. Available unit tests benches ------------------------------------------- - - tbrun --tag=comlib # comlib unit tests - tbrun --tag=serport # serport unit tests - tbrun --tag=rlink # rlink unit tests - tbrun --tag=issi # SRAM model unit tests - tbrun --tag=micron # CRAM model unit tests - tbrun --tag=sram_memctl # SRAM controller unit tests - tbrun --tag=cram_memctl # CRAM controller unit tests - tbrun --tag=w11a # w11a unit tests - -7. Available system tests benches ----------------------------------------- - - tbrun --tag=sys_tst_serloop.* # all sys_tst_serloop designs - tbrun --tag=sys_tst_rlink # all sys_tst_rlink designs - tbrun --tag=sys_tst_rlink_cuff # all sys_tst_rlink_cuff designs - tbrun --tag=sys_tst_sram # all sys_tst_sram designs - tbrun --tag=sys_w11a # all w11a designs diff --git a/doc/man/man1/asm-11_expect.1 b/tools/man/man1/asm-11_expect.1 similarity index 100% rename from doc/man/man1/asm-11_expect.1 rename to tools/man/man1/asm-11_expect.1 diff --git a/doc/man/man1/config_wrapper.1 b/tools/man/man1/config_wrapper.1 similarity index 100% rename from doc/man/man1/config_wrapper.1 rename to tools/man/man1/config_wrapper.1 diff --git a/doc/man/man1/console_starter.1 b/tools/man/man1/console_starter.1 similarity index 100% rename from doc/man/man1/console_starter.1 rename to tools/man/man1/console_starter.1 diff --git a/doc/man/man1/create_disk.1 b/tools/man/man1/create_disk.1 similarity index 100% rename from doc/man/man1/create_disk.1 rename to tools/man/man1/create_disk.1 diff --git a/doc/man/man1/dmscntanal.1 b/tools/man/man1/dmscntanal.1 similarity index 100% rename from doc/man/man1/dmscntanal.1 rename to tools/man/man1/dmscntanal.1 diff --git a/doc/man/man1/dmscntconv.1 b/tools/man/man1/dmscntconv.1 similarity index 100% rename from doc/man/man1/dmscntconv.1 rename to tools/man/man1/dmscntconv.1 diff --git a/doc/man/man1/file2tap.1 b/tools/man/man1/file2tap.1 similarity index 100% rename from doc/man/man1/file2tap.1 rename to tools/man/man1/file2tap.1 diff --git a/doc/man/man1/fx2load_wrapper.1 b/tools/man/man1/fx2load_wrapper.1 similarity index 100% rename from doc/man/man1/fx2load_wrapper.1 rename to tools/man/man1/fx2load_wrapper.1 diff --git a/doc/man/man1/njobihtm.1 b/tools/man/man1/njobihtm.1 similarity index 100% rename from doc/man/man1/njobihtm.1 rename to tools/man/man1/njobihtm.1 diff --git a/doc/man/man1/rm_dep.1 b/tools/man/man1/rm_dep.1 similarity index 100% rename from doc/man/man1/rm_dep.1 rename to tools/man/man1/rm_dep.1 diff --git a/doc/man/man1/svn_set_ignore.1 b/tools/man/man1/svn_set_ignore.1 similarity index 100% rename from doc/man/man1/svn_set_ignore.1 rename to tools/man/man1/svn_set_ignore.1 diff --git a/doc/man/man1/tap2file.1 b/tools/man/man1/tap2file.1 similarity index 100% rename from doc/man/man1/tap2file.1 rename to tools/man/man1/tap2file.1 diff --git a/doc/man/man1/tbfilt.1 b/tools/man/man1/tbfilt.1 similarity index 100% rename from doc/man/man1/tbfilt.1 rename to tools/man/man1/tbfilt.1 diff --git a/doc/man/man1/tbrun.1 b/tools/man/man1/tbrun.1 similarity index 100% rename from doc/man/man1/tbrun.1 rename to tools/man/man1/tbrun.1 diff --git a/doc/man/man1/tbrun_tbw.1 b/tools/man/man1/tbrun_tbw.1 similarity index 100% rename from doc/man/man1/tbrun_tbw.1 rename to tools/man/man1/tbrun_tbw.1 diff --git a/doc/man/man1/tbrun_tbwrri.1 b/tools/man/man1/tbrun_tbwrri.1 similarity index 100% rename from doc/man/man1/tbrun_tbwrri.1 rename to tools/man/man1/tbrun_tbwrri.1 diff --git a/doc/man/man1/tbw.1 b/tools/man/man1/tbw.1 similarity index 100% rename from doc/man/man1/tbw.1 rename to tools/man/man1/tbw.1 diff --git a/doc/man/man1/ti_rri.1 b/tools/man/man1/ti_rri.1 similarity index 100% rename from doc/man/man1/ti_rri.1 rename to tools/man/man1/ti_rri.1 diff --git a/doc/man/man1/ti_w11.1 b/tools/man/man1/ti_w11.1 similarity index 100% rename from doc/man/man1/ti_w11.1 rename to tools/man/man1/ti_w11.1 diff --git a/doc/man/man1/vbomconv.1 b/tools/man/man1/vbomconv.1 similarity index 100% rename from doc/man/man1/vbomconv.1 rename to tools/man/man1/vbomconv.1 diff --git a/doc/man/man1/xise_ghdl_simprim.1 b/tools/man/man1/xise_ghdl_simprim.1 similarity index 100% rename from doc/man/man1/xise_ghdl_simprim.1 rename to tools/man/man1/xise_ghdl_simprim.1 diff --git a/doc/man/man1/xise_ghdl_unisim.1 b/tools/man/man1/xise_ghdl_unisim.1 similarity index 100% rename from doc/man/man1/xise_ghdl_unisim.1 rename to tools/man/man1/xise_ghdl_unisim.1 diff --git a/doc/man/man1/xise_msg_filter.1 b/tools/man/man1/xise_msg_filter.1 similarity index 100% rename from doc/man/man1/xise_msg_filter.1 rename to tools/man/man1/xise_msg_filter.1 diff --git a/doc/man/man1/xise_msg_summary.1 b/tools/man/man1/xise_msg_summary.1 similarity index 100% rename from doc/man/man1/xise_msg_summary.1 rename to tools/man/man1/xise_msg_summary.1 diff --git a/doc/man/man1/xtwi.1 b/tools/man/man1/xtwi.1 similarity index 100% rename from doc/man/man1/xtwi.1 rename to tools/man/man1/xtwi.1 diff --git a/doc/man/man1/xtwv.1 b/tools/man/man1/xtwv.1 similarity index 100% rename from doc/man/man1/xtwv.1 rename to tools/man/man1/xtwv.1 diff --git a/doc/man/man1/xviv_ghdl_unisim.1 b/tools/man/man1/xviv_ghdl_unisim.1 similarity index 100% rename from doc/man/man1/xviv_ghdl_unisim.1 rename to tools/man/man1/xviv_ghdl_unisim.1 diff --git a/doc/man/man1/xviv_msg_filter.1 b/tools/man/man1/xviv_msg_filter.1 similarity index 100% rename from doc/man/man1/xviv_msg_filter.1 rename to tools/man/man1/xviv_msg_filter.1 diff --git a/doc/man/man1/xviv_msg_summary.1 b/tools/man/man1/xviv_msg_summary.1 similarity index 100% rename from doc/man/man1/xviv_msg_summary.1 rename to tools/man/man1/xviv_msg_summary.1 diff --git a/doc/man/man1/xviv_sim_vhdl_cleanup.1 b/tools/man/man1/xviv_sim_vhdl_cleanup.1 similarity index 100% rename from doc/man/man1/xviv_sim_vhdl_cleanup.1 rename to tools/man/man1/xviv_sim_vhdl_cleanup.1 diff --git a/doc/man/man5/vbom.5 b/tools/man/man5/vbom.5 similarity index 100% rename from doc/man/man5/vbom.5 rename to tools/man/man5/vbom.5