From 75a730e3b56f0dd66ea766f17bcddffd0ff3e58a Mon Sep 17 00:00:00 2001 From: wfjm Date: Sat, 4 Feb 2023 12:00:19 +0100 Subject: [PATCH] docu updates [skip ci] --- README.md | 43 +++-- doc/INSTALL_simh.md | 56 +++---- doc/README_known_issues.md | 14 +- doc/README_resolved_issues.md | 17 ++ doc/w11a_backend_setup.md | 73 ++++++++ doc/w11a_board_connection.md | 38 +++++ doc/w11a_diff_70_cache_memory.md | 22 +++ doc/w11a_io_emulation.md | 55 ++++++ doc/w11a_known_differences.md | 1 + doc/w11a_os_guide.md | 252 ++-------------------------- doc/w11a_simh_setup.md | 34 ++++ tools/oskit/211bsd_rk/README.md | 12 +- tools/oskit/211bsd_rl/README.md | 12 +- tools/oskit/211bsd_rp/README.md | 12 +- tools/oskit/211bsd_rpeth/README.md | 12 +- tools/oskit/211bsd_rpmin/README.md | 12 +- tools/oskit/211bsd_tm/README.md | 12 +- tools/oskit/README.md | 4 +- tools/oskit/rsx11m-31_rk/README.md | 16 +- tools/oskit/rsx11m-40_rk/README.md | 16 +- tools/oskit/rsx11mp-30_rp/README.md | 16 +- tools/oskit/rt11-40_rk/README.md | 16 +- tools/oskit/rt11-53_rl/README.md | 16 +- tools/oskit/u5ed_rk/README.md | 12 +- tools/oskit/u7ed_rp/README.md | 12 +- tools/oskit/xxdp_rl/README.md | 16 +- 26 files changed, 401 insertions(+), 400 deletions(-) create mode 100644 doc/w11a_backend_setup.md create mode 100644 doc/w11a_board_connection.md create mode 100644 doc/w11a_diff_70_cache_memory.md create mode 100644 doc/w11a_io_emulation.md create mode 100644 doc/w11a_simh_setup.md diff --git a/README.md b/README.md index 9c8dc739..d35e5a94 100644 --- a/README.md +++ b/README.md @@ -23,31 +23,38 @@ and a rather complete set of UNIBUS peripherals and last but not least a cache and memory controllers for SRAM, PSRAM and SDRAM (via Xilinx MIG core). The design is **FPGA proven**, runs currently on Digilent -[Arty A7](rtl/sys_gen/w11a/arty), -[Basys3](rtl/sys_gen/w11a/basys3), -[Cmod A7](rtl/sys_gen/w11a/cmoda7), -[Nexys A7](rtl/sys_gen/w11a/nexys4d), -[Nexys4](rtl/sys_gen/w11a/nexys4), -[Nexys3](rtl/sys_gen/w11a/nexys3), -[Nexys2](rtl/sys_gen/w11a/nexys2) and -[S3board](rtl/sys_gen/w11a/s3board) +[Arty A7](rtl/sys_gen/w11a/arty/README.md), +[Basys3](rtl/sys_gen/w11a/basys3/README.md), +[Cmod A7](rtl/sys_gen/w11a/cmoda7/README.md), +[Nexys A7](rtl/sys_gen/w11a/nexys4d/README.md), +[Nexys4](rtl/sys_gen/w11a/nexys4/README.md), +[Nexys3](rtl/sys_gen/w11a/nexys3/README.md), +[Nexys2](rtl/sys_gen/w11a/nexys2/README.md) and +[S3board](rtl/sys_gen/w11a/s3board/README.md) boards and boots 5th Edition UNIX, 2.11BSD UNIX, as well as various DEC operating systems from provided [oskits](tools/oskit/README.md). +The current implementation forwards the IO requests from all devices via a +fast serial connection to a backend server on a PC, which translates these +requests and maps them to contemporary interfaces. +True standalone systems are on the project roadmap. + For more information look into: -- w11 project [home page](https://wfjm.github.io/home/w11/) - and [blog](https://wfjm.github.io/blogs/w11/) -- [change log](doc/CHANGELOG.md) - and [installation notes](doc/INSTALL.md) -- guides to build bit files and test benches +- w11 project [home page](https://wfjm.github.io/home/w11/), especially the + sections on [feature set](https://wfjm.github.io/home/w11/impl/) and + [overall architecture](https://wfjm.github.io/home/w11/impl/architecture.html). +- w11 project [blog](https://wfjm.github.io/blogs/w11/). +- [change log](doc/CHANGELOG.md). + and [installation notes](doc/INSTALL.md). +- guides to build bit files and test benches. with [Xilinx Vivado](doc/README_buildsystem_Vivado.md) - and [Xilinx ISE](doc/README_buildsystem_ISE.md) + and [Xilinx ISE](doc/README_buildsystem_ISE.md). - guides to [run test benches](doc/w11a_tb_guide.md) - and to [boot operating systems](doc/w11a_os_guide.md) -- known [issues](doc/README_known_issues.md) -- known [differences](doc/w11a_known_differences.md) + and to [boot operating systems](doc/w11a_os_guide.md). +- known [issues](doc/README_known_issues.md). +- known [differences](doc/w11a_known_differences.md). - the impatient readers can try their luck with the - [quick start guide](doc/INSTALL_quickstart.md) + [quick start guide](doc/INSTALL_quickstart.md). A short description of the directory layout [is provided separately](https://wfjm.github.io/home/w11/impl/dirlayout.html), diff --git a/doc/INSTALL_simh.md b/doc/INSTALL_simh.md index 2279ab48..c3f8bebe 100644 --- a/doc/INSTALL_simh.md +++ b/doc/INSTALL_simh.md @@ -1,33 +1,18 @@ # Installation of the SimH pdp11 simulator +## SimH Classic The w11 project uses the pdp11 simulator from the [SimH](https://en.wikipedia.org/wiki/SIMH) project. The project was started -by Bob Supnik under [simh.trailing-edge.com](http://simh.trailing-edge.com). -This site contains the "classic" version of SimH, the 3.X stream, with v3.11-1 -as the last release. Since about 2014 the project is continued by a team led by -Mark Pizzolato as GitHub project [simh/simh](https://github.com/simh/simh). -The new, functionally much enhanced, version is called V4.*. However, the -team decided not to provide releases anymore, just a stream of commits, +by Bob Supnik under [simh.trailing-edge.com](http://simh.trailing-edge.com), +is still maintained, and offers the 3.X stream of SimH releases. + +## GitHub simh/simH +Since about 2014 the project is expanded and continued as GitHub project +[simh/simh](https://github.com/simh/simh) led by Mark Pizzolato. +The new, functionally much enhanced, version is called V4.*. However, this +project decided not to provide releases anymore, just a stream of commits, more than 4200 as of April 2022. -Debian and Ubuntu offer `simh` packages, but with the obsolete version V3.8.1, -released in February 2009. The main obstacle to the inclusion of newer -versions is, according to the Debian maintainer, the unclear license situation. - -The only practical way to obtain the pdp11 simulator is by installation from -sources. The GitHub repository contains also the classical versions, nicely -marked with tags. - -The `scmd` scripts provided in the w11 project were originally developed for -SimH 3.8, and worked for SimH 3.9 and later releases. The SimH 4.* development -over time became incompatible with the `scmd` scripts used for w11 verification. -See issue [#30](https://github.com/wfjm/w11/issues/30) for details. - -The bottom line at the moment: -- install SimH from [simh/simh](https://github.com/simh/simh) -- checkout `v3.11-1` - -## SimH license changes The maintainer of the [simh/simh](https://github.com/simh/simh) GitHub project, [Mark Pizzolato](https://github.com/markpizz), decided on May 15th, 2022 with commit [ce2adce6](https://github.com/simh/simh/commit/ce2adce6) to change the @@ -42,10 +27,7 @@ SimH mailing list [simh@groups.io](https://groups.io/g/simh), starting with post See especially Bob Supnik's post [SimH licensing and the state of the project](https://groups.io/g/simh/topic/simh_licensing_and_the_state/91173868). -Given that situation using version `v3.11-1` as described above is the -only prudent option for the time being. - -## Open-SimH relaunch +## GitHub open-simh/simh The post [Announcing the Open SIMH project](https://groups.io/g/simh/topic/91528716) announed on 2022-06-03 a re-launch of SimH as FOSS project. @@ -53,8 +35,20 @@ A new repository [open-simh/simh](https://github.com/open-simh/simh#readme) has been set up and provides the SimH code-base under an [MIT-style licence](https://en.wikipedia.org/wiki/MIT_License), see [LICENSE.txt](https://github.com/open-simh/simh/blob/master/LICENSE.txt). +Releases are being prepared, but not offered as of 2023-02-03. -The community will certainly move to open-simh, so best solution is currently -- install SimH from [open-simh/simh](https://github.com/simh/open-simh) -- checkout `v3.11-1` +## Debian packages +Debian and Ubuntu offer `simh` packages, but with the obsolete version V3.8.1, +released in February 2009. The main obstacle to the inclusion of newer +versions is, according to the Debian maintainer, the unclear license situation. +## Installing SimH +The only practical way to obtain an up-to-date SimH PDP-11 simulator is by +installation from sources. The currently best solution is to install the +latest SimH classic release, URL see above. + +## SimH startup script provided in the w11 project +The `scmd` scripts provided in the w11 project were originally developed for +SimH Classic 3.8, and worked for SimH Classic 3.9 and later releases. +They should also work for simh/simh and open-simh/simh, but are currently +most tested with Classic. diff --git a/doc/README_known_issues.md b/doc/README_known_issues.md index 91e736dc..00809978 100644 --- a/doc/README_known_issues.md +++ b/doc/README_known_issues.md @@ -1,20 +1,8 @@ # Known issues Notes -- resolved issues are summarized in [resolved issues](README_resolved_issues.md) +- resolved issues are summarized in [resolved issues](README_resolved_issues.md). - the case id indicates the release when the issue was first recognized. -### V0.791-5 {[issue #37](https://github.com/wfjm/w11/issues/37)} -- PSW changed after MMU aborts in dstw flows - -The dstw flow updates the condition codes before the the last possible -MMU abort. Example is the ccwe = 1 in s_dstw_def. -The condition codes are therefore changed when an MMU abort happens. - -Detected in a code rewiew. -Not practical consequences because only CLR, SXT, and MOV are affected. -Only SXT depends on a condition code (N), but doesn't change this cc. -Therefore, an instruction re-execution will always give the correct result. -But clearly a BUG, the condition codes must not change in case of MMU aborts. - ### V0.50-2 {[issue #28](https://github.com/wfjm/w11/issues/28)} -- RK11: write protect action too slow Some simple RK11 drivers, especially in test codes, don't poll for completion diff --git a/doc/README_resolved_issues.md b/doc/README_resolved_issues.md index 78750f3a..5c00a11e 100644 --- a/doc/README_resolved_issues.md +++ b/doc/README_resolved_issues.md @@ -1,5 +1,22 @@ # Resolved issues +### V0.791-5 {[issue #37](https://github.com/wfjm/w11/issues/37)} -- PSW changed after MMU aborts in dstw flows + +#### Original Issue +The dstw flow updates the condition codes before the the last possible +MMU abort. Example is the ccwe = 1 in s_dstw_def. +The condition codes are therefore changed when an MMU abort happens. + +Detected in a code rewiew. +Not practical consequences because only CLR, SXT, and MOV are affected. +Only SXT depends on a condition code (N), but doesn't change this cc. +Therefore, an instruction re-execution will always give the correct result. +But clearly a BUG, the condition codes must not change in case of MMU aborts. + +#### Fix +Fixed with commit [b59d545](https://github.com/wfjm/w11/commit/b59d545), +see [ECO-039](ECO-039-cc_and_aborts.md). + ### V0.50-3 {[issue #27](https://github.com/wfjm/w11/issues/27)} -- CPU: no mmu trap when instruction which clears trap enable itself causes a trap #### Original Issue diff --git a/doc/w11a_backend_setup.md b/doc/w11a_backend_setup.md new file mode 100644 index 00000000..e9ebbae2 --- /dev/null +++ b/doc/w11a_backend_setup.md @@ -0,0 +1,73 @@ +# Rlink and Backend Server setup + +After a board has been [connected and configured](w11a_board_connection.md) +and `vt100` emulator windows have been started with `console_starter`, +the backend server can be started and an [oskits](../tools/oskit/README.md) +or a _bare metal_ code like an [mcode](../tools/mcode/README.md) be executed. + +The first step is to ensure that the switches on the FPGA board have the correct +setting for w11 operation. The usage of the available switches, bottons and +LEDs is documented in the top entity of the respective design. The default +setting for w11 operation is given in the next section. + +Finally, the backend server is started the `ti_w11` quick start wrapper script +``` + ti_w11