github.com/wfjm.w11
1
0
Fork 0
mirror of https://github.com/wfjm/w11.git synced 2026-03-26 18:33:31 +00:00
Code Issues Releases Wiki Activity

convert .txt to .md; move doc/man to tools/man

Browse Source
This commit is contained in:
Walter F.J. Mueller
2016-12-22 12:03:34 +01:00
parent 529f465697
commit 07f86e59d8
73 changed files with 3458 additions and 3481 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
COPYING.md Normal file
View File

@@ -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).

16
COPYING.txt
View File

@@ -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

7
INSTALL.txt
View File

@@ -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

9
README.md
View File

@@ -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

472
doc/README-w11a_V.50-w11a_V0.60.txt → doc/CHANGELOG-w11a_V0.50-w11a_V0.60.md
View File

@@ -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) <a name="w11a_V0.60"></a>
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) <a name="w11a_V0.581"></a>
- 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) <a name="w11a_V0.58"></a>
- 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) <a name="w11a_V0.57"></a>
- 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) <a name="w11a_V0.562"></a>
- 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) <a name="w11a_V0.561"></a>
- 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) <a name="w11a_V0.56"></a>
- 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) <a name="w11a_V0.55"></a>
- 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) <a name="w11a_V0.54"></a>
- 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) <a name="w11a_V0.532"></a>
- 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) <a name="w11a_V0.531"></a>
- 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) <a name="w11a_V0.53"></a>
- 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) <a name="w11a_V0.52"></a>
- 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) <a name="w11a_V0.51"></a>
- 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 <a name="w11a_V0.5"></a>
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

616
doc/CHANGELOG-w11a_V0.60-w11a_V0.70.md Normal file
View File

@@ -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) <a name="w11a_V0.70"></a>
### 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) <a name="w11a_V0.66"></a>
### 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) <a name="w11a_V0.65"></a>
### 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) <a name="v0.64"></a>
### 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) <a name="w11a_V0.63"></a>
### 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) <a name="v0.62"></a>
### 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) <a name="w11a_V0.61"></a>
### 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=<board name>` 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

603
doc/CHANGELOG-w11a_V0.70-w11a_V0.74.md Normal file
View File

@@ -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) <a name="w11a_V0.74"></a>
### 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.<mode>.<stem>
- 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) <a name="w11a_V0.73"></a>
### 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) <a name="w11a_V0.72"></a>
### 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) <a name="w11a_V0.71"></a>
### 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

16
doc/CHANGELOG.md Normal file
View File

@@ -0,0 +1,16 @@
# Changelog: w11a_V0.74 -> master
### Table of contents
- Current [master](#user-content-master)
<!-- - Release [w11a_V0.741](#user-content-w11a_V0.741) -->
- [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 <a name="master"></a>
### Summary
- converted documentation from plain text to markdown

114
doc/ECO-026-div.md Normal file
View File

@@ -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.

108
doc/ECO-026-div.txt
View File

@@ -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.

47
doc/ECO-027-trap_mmu.md Normal file
View File

@@ -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.

46
doc/ECO-027-trap_mmu.txt
View File

@@ -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.

71
doc/FILES.txt
View File

@@ -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

301
doc/INSTALL.md Normal file
View File

@@ -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 <a name="download"></a>
All instructions below assume that the project files reside in a
working directory with the name represented as `<install-dir>`
- to download the repository
git clone https://github.com/wfjm/w11
- use the latest snapshop under `master`
cd <install-dir>
git checkout master
- to use tagged verions list available tags
cd <install-dir>
git tag -l
and select one of them
cd <install-dir>
git checkout tags/<tag>
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 <a name="sysreq"></a>
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 <a name="envvar"></a>
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=<install-dir>
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 <a name="ghdl-lib"></a>
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 <a name="build-tools"></a>
#### Compile sharable libraries <a name="build-cpp"></a>
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 <a name="build-tcl"></a>
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 <a name="build-system"></a>
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 <a name="build-fpga"></a>
Ready to build designs are organized in the directories
$RETROBASE/rtl/sys_gen/<design>/<board>
with <design>
w11a w11a system
tst_rlink rlink over serial link tester
tst_rlink_cuff rlink over FX2 interface tester
and <board>
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/<design>/<board>
make sys_<dtype>_<btype>.bit
with in most cases
- `<dtype>` = `<design>`
- `<code>` = 2 letter abbreviation for the board, e.g. n4 for nexys4.
### Available bitkits with bit and log files <a name="bitkits"></a>
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:
<release>_<tool>_<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 <design>.bit
fx2load_wrapper --board=nexys3
xtwi config_wrapper --board=nexys3 jconfig <design>.svf
- for Digilent Nexys2 board (using Cypress FX2 USB controller)
xtwi config_wrapper --board=nexys2 bit2svf <design>.bit
fx2load_wrapper --board=nexys2
xtwi config_wrapper --board=nexys2 jconfig <design>.svf
- for Digilent S3board (using ISE Impact)
xtwi config_wrapper --board=s3board iconfig <design>.bit
### Generate Doxygen based source code view <a name="build-doxy"></a>
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 <desired root of html documentation>
./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 &

322
doc/INSTALL.txt
View File

@@ -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 <wdir>
- to download latest snapshot of trunk
cd <wdir>
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 <wdir>
svn co http://opencores.org/ocsvn/w11/w11/tags/<tag>
- 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 <wdir>
svn co -r <rev> 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=<wdir>
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:
<setup XTWI_PATH, see section 6a.>
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/<design>/<board>
with <design>
w11a w11a system
tst_rlink rlink over serial link tester
tst_rlink_cuff rlink over FX2 interface tester
and <board>
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/<design>/<board>
make sys_<dtype>_<btype>.bit
with in most cases <dtype> = <design> and <code> = 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:
<release>_<tool>_<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 <design>.bit
fx2load_wrapper --board=nexys3
xtwi config_wrapper --board=nexys3 jconfig <design>.svf
b. for Digilent Nexys2 board (using Cypress FX2 USB controller)
xtwi config_wrapper --board=nexys2 bit2svf <design>.bit
fx2load_wrapper --board=nexys2
xtwi config_wrapper --board=nexys2 jconfig <design>.svf
c. for Digilent S3board (using ISE Impact)
xtwi config_wrapper --board=s3board iconfig <design>.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 <desired root of html documentation>
./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 &

28
doc/INSTALL_from_opencores.md Normal file
View File

@@ -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 <install-dir>
svn co http://opencores.org/ocsvn/w11/w11/tags/<tag>
- 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 <install-dir>
svn co -r <rev> http://opencores.org/ocsvn/w11/w11/trunk

77
doc/INSTALL_fx2_support.md Normal file
View File

@@ -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 <a name="sysreq"></a>
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 <a name="envvar"></a>
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 <a name="usb-access"></a>
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 <a name="fx2-firmware"></a>
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.

79
doc/INSTALL_fx2_support.txt
View File

@@ -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.

28
doc/INSTALL_ghdl.txt → doc/INSTALL_ghdl.md
View File

@@ -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

50
doc/INSTALL_urjtag.md Normal file
View File

@@ -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.

51
doc/INSTALL_urjtag.txt
View File

@@ -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.

620
doc/README-w11a_V.60-w11a_V0.70.txt
View File

@@ -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=<board name> 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

643
doc/README.txt
View File

@@ -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.<mode>.<stem>
- 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

87
doc/README_Rlink_V4.md Normal file
View File

@@ -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 <nakbyte> EOP
- the nakbyte has the redundant format
10<!nakcode><nakcode>
- 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

76
doc/README_Rlink_V4.txt
View File

@@ -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 <nakbyte> EOP
- the nakbyte has the redundant format
10<!nakcode><nakcode>
- 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

58
doc/README_USB-VID-PID.md Normal file
View File

@@ -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!**

55
doc/README_USB-VID-PID.txt
View File

@@ -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

246
doc/README_buildsystem_ISE.md Normal file
View File

@@ -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 <a name="concept"></a>
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 <a name="sysenv"></a>
#### Setup environment variables <a name="envvar"></a>
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 name="ghdllibs"></a>
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 <a name="buildtb"></a>
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 <a name="buildtb-ghdl"></a>
To compile a ghdl based test bench named `<tbench>` all is needed is
make <tbench>
The make file will use `<tbench>.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 <tbench>_ssim # for post-xst (using UNISIM)
make <tbench>_fsim # for post-map (using SIMPRIM)
make <tbench>_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 <a name="buildtb-isim"></a>
To compile a ISE ISim based test bench named `<tbench>` all is needed is
make <tbench>_ISim
The make file will use `<tbench>.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 <tbench>_ISim_ssim # for post-xst
make <tbench>_ISim_fsim # for post-map
make <tbench>_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 <a name="buildfpga"></a>
To generate a bit file for a system named `<sys>` all is needed is
make <sys>.bit
The make file will use `<sys>.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
<sys>_xst.log # xst log file
<sys>_tra.log # translate (ngdbuild) log file (renamed %.bld)
<sys>_map.log # map log file (renamed %_map.mrp)
<sys>_par.log # par log file (renamed %.par)
<sys>_pad.log # pad file (renamed %_pad.txt)
<sys>_twr.log # trce log file (renamed %.twr)
<sys>_tsi.log # trce tsi file (renamed %.tsi)
<sys>_bgn.log # bitgen log file (renamed %.bgn)
If only the xst or par output is wanted just use
make <sys>.ngc
make <sys>.ncd
Some tools require a `.svf` rather than a `.bit` file. It can be created with
make <sys>.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 <sys>.mfsum
after a re-build.
### Configuring FPGAs (via make flow) <a name="config-make"></a>
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 <sys>.iconfig
For using the Cypress FX2 USB controller on Digilent Nexys2, Nexys3 and
Atlys boards just connect the USB cable and
make <sys>.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`) <a name="config-wrap"></a>
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 <a name="artix"></a>
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 <target>
an ISE based build. To be used for tool comparisons, the ISE generated bit
files were never tested in an FPGA.

239
doc/README_buildsystem_ISE.txt
View File

@@ -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 <tbench> all is needed is
make <tbench>
The make file will use <tbench>.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 <tbench>_ssim # for post-xst (using UNISIM)
make <tbench>_fsim # for post-map (using SIMPRIM)
make <tbench>_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 <tbench> all is needed is
make <tbench>_ISim
The make file will use <tbench>.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 <tbench>_ISim_ssim # for post-xst
make <tbench>_ISim_fsim # for post-map
make <tbench>_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 <sys> all is needed is
make <sys>.bit
The make file will use <sys>.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
<sys>_xst.log # xst log file
<sys>_tra.log # translate (ngdbuild) log file (renamed %.bld)
<sys>_map.log # map log file (renamed %_map.mrp)
<sys>_par.log # par log file (renamed %.par)
<sys>_pad.log # pad file (renamed %_pad.txt)
<sys>_twr.log # trce log file (renamed %.twr)
<sys>_tsi.log # trce tsi file (renamed %.tsi)
<sys>_bgn.log # bitgen log file (renamed %.bgn)
If only the xst or par output is wanted just use
make <sys>.ngc
make <sys>.ncd
Some tools require a .svf rather than a .bit file. It can be created with
make <sys>.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 <sys>.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 <sys>.iconfig
For using the Cypress FX2 USB controller on Digilent Nexys2, Nexys3 and
Atlys boards just connect the USB cable and
make <sys>.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 <target>
an ISE based build. To be used for tool comparisons, the ISE generated bit
files were never tested in an FPGA.

274
doc/README_buildsystem_Vivado.md Normal file
View File

@@ -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 <a name="concept"></a>
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 <a name="sysenv"></a>
#### Setup environment variables <a name="envvar"></a>
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 name="ghdllibs"></a>
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 <a name="buildtb"></a>
The build flows currently supports ghdl and the vivado simulator xsim.
#### With ghdl <a name="buildtb-ghdl"></a>
To compile a ghdl based test bench named `<tbench>` all is needed is
make <tbench>
The make file will use `<tbench>.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 <tbench>_ssim # for post synthesis functional
make <tbench>_osim # for post optimize functional
make <tbench>_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 <a name="buildtb-xsim"></a>
To compile a Vivado xsim based test bench named <tbench> all is needed is
make <tbench>_XSim
The make file will use `<tbench>.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 <tbench>_XSim_ssim # for post-synthesis functional
make <tbench>_XSim_osim # for post-optimize functional
make <tbench>_XSim_rsim # for post-routing functional
make <tbench>_XSim_esim # for post-synthesis timing
make <tbench>_XSim_psim # for post-optimize timing
make <tbench>_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 <a name="buildfpga"></a>
To generate a bit file for a system named `<sys>` all is needed is
make <sys>.bit
The make file will use `<sys>.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
<sys>_syn.log # synthesis log (from runme.log)
<sys>_imp.log # implementation log (from runme.log)
<sys>_bit.log # write_bitstream log (from runme.log)
<sys>_syn_util.rpt # (from <sys>_utilization_synth.rpt)
<sys>_opt_drc.rpt # (from <sys>_opt_drc.rpt)
<sys>_pla_io.rpt # (from <sys>_io_placed.rpt)
<sys>_pla_clk.rpt # (from <sys>_clock_utilization_placed.rpt)
<sys>_pla_util.rpt # (from <sys>_utilization_placed.rpt)
<sys>_pla_cset.rpt # (from <sys>_control_sets_placed.rpt)
<sys>_rou_sta.rpt # (from <sys>_route_status.rpt)
<sys>_rou_drc.rpt # (from <sys>_drc_routed.rpt)
<sys>_rou_tim.rpt # (from <sys>_timing_summary_routed.rpt)
<sys>_rou_pwr.rpt # (from <sys>_power_routed.rpt)
<sys>_rou_util.rpt # (extra report_utilization)
<sys>_rou_util_h.rpt # (extra report_utilization -hierarchical)
<sys>_ds.rpt # (extra report_datasheet)
The design check points are also kept
<sys>_syn.dcp # (from <sys>.dcp)
<sys>_opt.dcp # (from <sys>_opt.dcp)
<sys>_pla.dcp # (from <sys>_placed.dcp)
<sys>_rou.dcp # (from <sys>_routed.dcp)
If only the post synthesis, optimize or route design checkpoints are wanted
make <sys>_syn.dcp
make <sys>_opt.dcp
make <sys>_rou.dcp
### Building vivado projects, creating gate level models <a name="buildviv"></a>
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 <sys>.vivado # create vivado project from <sys>.vbom
make vivado # open project in project_mflow
make <sys>_ssim.vhd # post-synthesis functional model (vhdl)
make <sys>_osim.vhd # post-optimize functional model (vhdl)
make <sys>_rsim.vhd # post-routing functional model (vhdl)
make <sys>_ssim.v # post-synthesis functional model (verilog)
make <sys>_osim.v # post-optimize functional model (verilog)
make <sys>_rsim.v # post-routing functional model (verilog)
make <sys>_esim.v # post-synthesis timing model (verilog)
make <sys>_psim.v # post-optimize timing model (verilog)
make <sys>_tsim.v # post-routing timing model (verilog)
For timing model verilog file an associated sdf file is also generated.
### Configuring FPGAs <a name="config-fpga"></a>
The make flow supports also loading the bitstream into FPGAs via the
Vivado hardware server. Simply use
make <sys>.vconfig
Note: works with Arty, Basys3, and Nexys4, only one board must connected.
### Note on ISE <a name="ise"></a>
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 <target>
or
makeise <target>
an ISE based build. To be used for tool comparisons, the ISE generated bit
files were never tested in an FPGA.

267
doc/README_buildsystem_Vivado.txt
View File

@@ -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 <tbench> all is needed is
make <tbench>
The make file will use <tbench>.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 <tbench>_ssim # for post synthesis functional
make <tbench>_osim # for post optimize functional
make <tbench>_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 <tbench> all is needed is
make <tbench>_XSim
The make file will use <tbench>.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 <tbench>_XSim_ssim # for post-synthesis functional
make <tbench>_XSim_osim # for post-optimize functional
make <tbench>_XSim_rsim # for post-routing functional
make <tbench>_XSim_esim # for post-synthesis timing
make <tbench>_XSim_psim # for post-optimize timing
make <tbench>_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 <sys> all is needed is
make <sys>.bit
The make file will use <sys>.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
<sys>_syn.log # synthesis log (from runme.log)
<sys>_imp.log # implementation log (from runme.log)
<sys>_bit.log # write_bitstream log (from runme.log)
<sys>_syn_util.rpt # (from <sys>_utilization_synth.rpt)
<sys>_opt_drc.rpt # (from <sys>_opt_drc.rpt)
<sys>_pla_io.rpt # (from <sys>_io_placed.rpt)
<sys>_pla_clk.rpt # (from <sys>_clock_utilization_placed.rpt)
<sys>_pla_util.rpt # (from <sys>_utilization_placed.rpt)
<sys>_pla_cset.rpt # (from <sys>_control_sets_placed.rpt)
<sys>_rou_sta.rpt # (from <sys>_route_status.rpt)
<sys>_rou_drc.rpt # (from <sys>_drc_routed.rpt)
<sys>_rou_tim.rpt # (from <sys>_timing_summary_routed.rpt)
<sys>_rou_pwr.rpt # (from <sys>_power_routed.rpt)
<sys>_rou_util.rpt # (extra report_utilization)
<sys>_rou_util_h.rpt # (extra report_utilization -hierarchical)
<sys>_ds.rpt # (extra report_datasheet)
The design check points are also kept
<sys>_syn.dcp # (from <sys>.dcp)
<sys>_opt.dcp # (from <sys>_opt.dcp)
<sys>_pla.dcp # (from <sys>_placed.dcp)
<sys>_rou.dcp # (from <sys>_routed.dcp)
If only the post synthesis, optimize or route design checkpoints are wanted
make <sys>_syn.dcp
make <sys>_opt.dcp
make <sys>_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 <sys>.vivado # create vivado project from <sys>.vbom
make vivado # open project in project_mflow
make <sys>_ssim.vhd # post-synthesis functional model (vhdl)
make <sys>_osim.vhd # post-optimize functional model (vhdl)
make <sys>_rsim.vhd # post-routing functional model (vhdl)
make <sys>_ssim.v # post-synthesis functional model (verilog)
make <sys>_osim.v # post-optimize functional model (verilog)
make <sys>_rsim.v # post-routing functional model (verilog)
make <sys>_esim.v # post-synthesis timing model (verilog)
make <sys>_psim.v # post-optimize timing model (verilog)
make <sys>_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 <sys>.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 <target>
or
makeise <target>
an ISE based build. To be used for tool comparisons, the ISE generated bit
files were never tested in an FPGA.

70
doc/README_known_issues.md Normal file
View File

@@ -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}_

51
doc/README_known_issues.txt
View File

@@ -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}

6
doc/README_xadc.txt → doc/README_xadc.md
View File

@@ -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

95
doc/w11a_known_issues.md Normal file
View File

@@ -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) <a name="diff"></a>
- 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 <a name="lim"></a>
- 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 <a name="bug"></a>
- **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**

100
doc/w11a_known_issues.txt
View File

@@ -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.

289
doc/w11a_os_guide.md Normal file
View File

@@ -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 <a name="io-emu"></a>
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 <a name="fpga-setup"></a>
Recommended setups
- Arty
- connect USB cable to micro-USB connector labeled 'J10'
- to configure via vivado hardware server
make <sys>.vconfig
- Basys3
- connect USB cable to micro-USB connector labeled 'PROG'
- to configure via vivado hardware server
make <sys>.vconfig
- Nexys4
- connect USB cable to micro-USB connector labeled 'PROG'
- to configure via vivado hardware server
make <sys>.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 <sys>.jconfig
- Nexys2
- connect USB cable to mini-USB connector (between RS232 and PS/2 port)
- to configure via FX2 and jtag tool
make <sys>.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 <sys>.iconfig
### Rlink and Backend Server setup <a name="rlink"></a>
All examples below use the same basic setup
- setup `vt100` emulator windows
cd $RETROBASE/tools/oskit/<oskit-name>
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<dn>,12M,break,xon @<oskit-name>_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<dn>,12M,break,xon @<oskit-name>_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<dn>,12M,break,cts @<oskit-name>_boot.tcl
- for n2,n3 over fx2
SWI = 00101100
ti_w11 -u @<oskit-name>_boot.tcl
- for s3 serial
SWI = 00101010
ti_w11 -tu<dn>,460k,break,xon @<oskit-name>_boot.tcl
Notes:
- on `<dn>`, the serial device number
- check with `ls /dev/ttyUSB*` to see what is available
- `<dn>` 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.
- `<dn>` 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 <a name="simh"></a>
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/<oskit-name>
console_starter -s -d DL1 &
**Note**: the -s ensures that the port numbers used by simh are taken!
- start the simulator
pdp11 <oskit-name>_boot.scmd
###oskits <a name="oskits"></a>
Ready to be used 'oskits' are provided under
$RETROBASE/tools/oskit/<oskit-name>
The tarballs with the disk images are provided from a web server
and have to be installed separately.
###Unix systems <a name="oskits-unix"></a>
#### 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_<oskit-name>set.txt` file in the
oskit directory.
### DEC operating systems <a name="oskits-dec"></a>
#### 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 ( `<kit>.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 ( `<kit>.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_<oskit-name>set.txt` file in the
oskit directory.

272
doc/w11a_os_guide.txt
View File

@@ -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 <sys>.vconfig
- Basys3
- connect USB cable to micro-USB connector labeled 'PROG'
- to configure via vivado hardware server
make <sys>.vconfig
- Nexys4
- connect USB cable to micro-USB connector labeled 'PROG'
- to configure via vivado hardware server
make <sys>.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 <sys>.jconfig
- Nexys2
- connect USB cable to mini-USB connector (between RS232 and PS/2 port)
- to configure via FX2 and jtag tool
make <sys>.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 <sys>.iconfig
3. Rlink and Backend Server setup -----------------------------------------
All examples below use the same basic setup
- setup vt100 emulator windows
cd $RETROBASE/tools/oskit/<oskit-name>
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 <boot-script> is given in the following sections
- for arty over serial
SWI = 0110 (gives console light emulation...)
ti_w11 -tu<dn>,12M,break,xon @<oskit-name>_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<dn>,12M,break,xon @<oskit-name>_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<dn>,12M,break,cts @<oskit-name>_boot.tcl
- for n2,n3 over fx2
SWI = 00101100
ti_w11 -u @<oskit-name>_boot.tcl
- for s3 serial
SWI = 00101010
ti_w11 -tu<dn>,460k,break,xon @<oskit-name>_boot.tcl
Notes:
- on <dn>, the serial device number
- check with 'ls /dev/ttyUSB*' to see what is available
- <dn> 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.
- <dn> 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/<oskit-name>
console_starter -s -d DL1 &
{Note: the -s ensures that the port numbers used by simh are taken!}
- start the simulator
pdp11 <oskit-name>_boot.scmd
5. oskits -----------------------------------------------------------------
Ready to be used 'oskits' are provided under
$RETROBASE/tools/oskit/<oskit-name>
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_<oskit-name>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 ( <kit>.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 ( <kit>.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_<oskit-name>set.txt file in the
oskit directory.

30
doc/w11a_seq_flow.md Normal file
View File

@@ -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 |

24
doc/w11a_seq_flow.txt
View File

@@ -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

182
doc/w11a_tb_guide.md Normal file
View File

@@ -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 <a name="env"></a>
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 <a name="tb-unit"></a>
All unit test are executed via `tbw` (test bench warpper) script.
- the test bench is run like
tbw <testbenchname> [stimfile] | tbfilt --tee <logfile>
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 <a name="tb-sys"></a>
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 <a name="tb-driver"></a>
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 <a name="tb-exec"></a>
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 <a name="list-tb-unit"></a>
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 <a name="list-tb-sys"></a>
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

178
doc/w11a_tb_guide.txt
View File

@@ -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 <testbenchname> [stimfile] | tbfilt --tee <logfile>
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

0
doc/man/man1/asm-11_expect.1 → tools/man/man1/asm-11_expect.1
View File

0
doc/man/man1/config_wrapper.1 → tools/man/man1/config_wrapper.1
View File

0
doc/man/man1/console_starter.1 → tools/man/man1/console_starter.1
View File

0
doc/man/man1/create_disk.1 → tools/man/man1/create_disk.1
View File

0
doc/man/man1/dmscntanal.1 → tools/man/man1/dmscntanal.1
View File

0
doc/man/man1/dmscntconv.1 → tools/man/man1/dmscntconv.1
View File

0
doc/man/man1/file2tap.1 → tools/man/man1/file2tap.1
View File

0
doc/man/man1/fx2load_wrapper.1 → tools/man/man1/fx2load_wrapper.1
View File

0
doc/man/man1/njobihtm.1 → tools/man/man1/njobihtm.1
View File

0
doc/man/man1/rm_dep.1 → tools/man/man1/rm_dep.1
View File

0
doc/man/man1/svn_set_ignore.1 → tools/man/man1/svn_set_ignore.1
View File

0
doc/man/man1/tap2file.1 → tools/man/man1/tap2file.1
View File

0
doc/man/man1/tbfilt.1 → tools/man/man1/tbfilt.1
View File

0
doc/man/man1/tbrun.1 → tools/man/man1/tbrun.1
View File

0
doc/man/man1/tbrun_tbw.1 → tools/man/man1/tbrun_tbw.1
View File

0
doc/man/man1/tbrun_tbwrri.1 → tools/man/man1/tbrun_tbwrri.1
View File

0
doc/man/man1/tbw.1 → tools/man/man1/tbw.1
View File

0
doc/man/man1/ti_rri.1 → tools/man/man1/ti_rri.1
View File

0
doc/man/man1/ti_w11.1 → tools/man/man1/ti_w11.1
View File

0
doc/man/man1/vbomconv.1 → tools/man/man1/vbomconv.1
View File

0
doc/man/man1/xise_ghdl_simprim.1 → tools/man/man1/xise_ghdl_simprim.1
View File

0
doc/man/man1/xise_ghdl_unisim.1 → tools/man/man1/xise_ghdl_unisim.1
View File

0
doc/man/man1/xise_msg_filter.1 → tools/man/man1/xise_msg_filter.1
View File

0
doc/man/man1/xise_msg_summary.1 → tools/man/man1/xise_msg_summary.1
View File

0
doc/man/man1/xtwi.1 → tools/man/man1/xtwi.1
View File

0
doc/man/man1/xtwv.1 → tools/man/man1/xtwv.1
View File

0
doc/man/man1/xviv_ghdl_unisim.1 → tools/man/man1/xviv_ghdl_unisim.1
View File

0
doc/man/man1/xviv_msg_filter.1 → tools/man/man1/xviv_msg_filter.1
View File

0
doc/man/man1/xviv_msg_summary.1 → tools/man/man1/xviv_msg_summary.1
View File

0
doc/man/man1/xviv_sim_vhdl_cleanup.1 → tools/man/man1/xviv_sim_vhdl_cleanup.1
View File

0
doc/man/man5/vbom.5 → tools/man/man5/vbom.5
View File