diff --git a/README.md b/README.md index 10def2ba..2b91fdf1 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,8 @@ For more information look into: and to [boot operating systems](doc/w11a_os_guide.md) - known issues [general](doc/README_known_issues.md) and [w11a CPU](doc/w11a_known_issues.md) +- the impatient readers can try their luck with the + [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/CHANGELOG.md b/doc/CHANGELOG.md index 81e006c3..d4889d76 100644 --- a/doc/CHANGELOG.md +++ b/doc/CHANGELOG.md @@ -2,6 +2,7 @@ ### Table of contents - Current [HEAD](#user-content-head) +- Release [w11a_V0.75](#user-content-w11a_V0.75) - Release [w11a_V0.742](#user-content-w11a_V0.742) - Release [w11a_V0.741](#user-content-w11a_V0.741) - [CHANGELOG for w11a_V.70 to w11a_V0.74](CHANGELOG-w11a_V0.70-w11a_V0.74.md) diff --git a/doc/INSTALL.md b/doc/INSTALL.md index ba30de84..0f46e1d5 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -12,6 +12,7 @@ - [The build system](#user-content-build-system) - [Available designs](#user-content-build-fpga) - [Available bitkits with bit and log files](#user-content-bitkits) +- [Configure FPGA](#user-content-fpgaconf) - [Generate Doxygen based source code view](#user-content-build-doxy) ### Download @@ -51,7 +52,7 @@ 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) + - Vivado WebPACK (for Series-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) @@ -229,11 +230,18 @@ Ready to build designs are organized in the directories tst_rlink_cuff rlink over FX2 interface tester and - basys3 b3: Digilent Basys3 board - nexys4 n4: Digilent Nexys4 board (cellular RAM version) - nexys3 n3: Digilent Nexys3 board - nexys2 n2: Digilent Nexys2 board (-1200 FPGA version) - s3board s3: Digilent S3board (-1000 FPGA version) + cmoda7 c7: Digilent Cmod A7 board + arty arty: Digilent Arty A7-35 board + basys3 b3: Digilent Basys3 board + nexys4d n4d: Digilent Nexys4 board (DDR RAM version) + 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) + + for w11a designs which only use BRAM as memory are provided + arty_bram br_arty: Digilent Arty A7-35 board + nexys4d_bram br_n4d: Digilent Nexys4 board (DDR RAM version) To build the designs locally use @@ -242,7 +250,7 @@ To build the designs locally use with in most cases - `` = `` -- `` = 2 letter abbreviation for the board, e.g. n4 for nexys4. +- `` = abbreviation for the board, e.g. n4 for nexys4. ### Available bitkits with bit and log files @@ -255,6 +263,7 @@ file names contain information about release, Xlinix tool, and design: __.tgz +### Configure FPGA - Vivado based designs: These designs can be loaded with the Vivado hardware server into the FPGA. @@ -265,7 +274,7 @@ file names contain information about release, Xlinix tool, and design: 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. + 3. `fx2load_wrapper` is needed once after each board power on. - for Digilent Nexys3 board (using Cypress FX2 USB controller) diff --git a/doc/INSTALL_quickstart.md b/doc/INSTALL_quickstart.md new file mode 100644 index 00000000..b5b4058e --- /dev/null +++ b/doc/INSTALL_quickstart.md @@ -0,0 +1,154 @@ +# Quick start Guide + +This _quick start guide_ describes the fastest possible path to a running +operating system on a w11 on current Series-7 based boards. It leaves out +legacy Spartan-3 and Spartan-6 designs, verification, test benches, test +designs, and many other aspects, for all this consult the full +[INSTALL](INSTALL.md) and the READMEs in [doc](.). This write-up +focuses on the steps _[prepare](#user-content-prepare)_, +_[build](#user-content-build)_ and _[boot](#user-content-boot)_, +and gives one [concrete example](#user-content-tested). + +### Prepare + +First all required software must be installed +- clone the w11 project, essentially + + git clone https://github.com/wfjm/w11 + + for details see [INSTALL#download](INSTALL.md#user-content-download). + +- ensure the packages required for the backend software are installed, + see [INSTALL#sysreq](INSTALL.md#user-content-sysreq), and that + Xilinx Vivado is installed. + +- setup the shell environment, + see [INSTALL#envvar](INSTALL.md#user-content-envvar), + + export RETROBASE= + export PATH=$PATH:$RETROBASE/tools/bin:. + export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$RETROBASE/tools/lib + + export TCLINC=/usr/include/tcl8.6 + export TCLLIBNAME=tcl8.6 + + export XTWV_PATH= + + setup the TCL environment, + see [INSTALL#build-tcl](INSTALL.md#user-content-build-tcl) + + cd $HOME + ln -s $RETROBASE/tools/tcl/.tclshrc . + ln -s $RETROBASE/tools/tcl/.wishrc . + + and ensure that USB `udev` rules for access and latency are setup, + see [tools/sys/README](../tools/sys/README.md). + +- compile the backend software tools + + cd $RETROBASE/tools/src + time make -j 4 + + cd $RETROBASE/tools/tcl + setup_packages + + see [INSTALL#build-tools](INSTALL.md#user-content-build-tools). + +### Build: generate bit file and configure FPGA + +All details of the Vivado implementation flow are encapsulated by the +[build system](doc/README_buildsystem_Vivado.md) in a simple `make` command + + cd $RETROBASE/rtl/sys_gen/w11a/ + time make sys_w11a_.bit + +with the currently supported combinations + + board btype memory Comment + cmoda7 c7 672 kB Digilent Cmod A7 board + arty_bram br_arty 176 kB Digilent Arty A7-35 board + basys3 b3 176 kB Digilent Basys3 board + nexys4d_bram br_n4d 512 kB Digilent Nexys4 board (DDR RAM) + nexys4 n4 3840 kB Digilent Nexys4 board (cellular RAM) + +The FPGA is configured via the vivado hardware server with + + make sys_w11a_.vconfig + +### Boot an operating system + +A variety of _oskits_ is provided under [tools/oskit](../tools/oskit). +The quick start guide describes only how to boot plain 2.11BSD. The +full featured [211bsd_rp](../tools/oskit/211bsd_rp/README.md) can be +used when more than 1024 kB memory is available, for systems with 512 to +1024 kB memory use the pruned down +[211bsd_rpmin](../tools/oskit/211bsd_rpmin/README.md). +For 2.11BSD with Ethernet, other OS and more details consult +[w11a_os_guide](w11a_os_guide.md). + +Key steps are +- consult the README in the oskit directory and download the disk image files, + typically with a `wget` and `tar` command + +- setup `vt100` emulator windows + + cd $RETROBASE/tools/oskit/ + console_starter -d DL0 & + console_starter -d DL1 & + +- configure the board switches _(important!!)_ and start the backend software + with the options as described in + [w11a_os_guide#rlink](w11a_os_guide.md.html#user-content-rlink), typically + + cd $RETROBASE/tools/oskit/ + ti_w11 @_boot.tcl + + Hit in the `DL0vt100` console window to connect, than follow + the expected startup sequence on the console `DL0vt100` is described in the + README in the oskit directory. + +### Concrete test run +The recipe was tested +- on 2018-08-04 +- after commit [6ee3ed6](https://github.com/wfjm/w11/commit/6ee3ed6) + + cd $RETROBASE/tools/src + time make -j 4 + # real 2m58.501s user 5m4.244s sys 0m35.600s + +- for design `nexys4` + + cd $RETROBASE/rtl/sys_gen/w11a/nexys4 + time make sys_w11a_n4.bit + # real 10m48.274s user 0m55.660s sys 0m3.160s + time make sys_w11a_n4.vconfig + # real 0m32.747s user 0m15.996s sys 0m0.736s + +- for oskit `211bsd_rp` + - in linux terminal + + cd $RETROBASE/tools/oskit/211bsd_rp + wget http://www.retro11.de/data/oc_w11/oskits/211bsd_rpset.tgz + tar -xzf 211bsd_rpset.tgz + + console_starter -d DL0 & + console_starter -d DL1 & + + # set board switches to SWI = 00000000 00101000 + ti_w11 -tuD,12M,break,cts @211bsd_rp_boot.tcl + + - in window `DL1vt100` hit to connect to backend, than see output and do required inputs as written in [README](../tools/oskit/211bsd_rp/README.md): + + 70Boot from xp(0,0,0) at 0176700 + : {} + : xp(0,0,0)unix + Boot: bootdev=05000 bootcsr=0176700 + ... + # ^D + ... + login: {root} + + - when done with exploring 2.11BSD do proper system shutdown + - in 211bsd session type `shutdown` + - in ti_w11 session wait for `CPU attention` and `H:cpu0` prompt, + than exit with `^D`. diff --git a/doc/w11a_os_guide.md b/doc/w11a_os_guide.md index a747f12c..01104bf0 100644 --- a/doc/w11a_os_guide.md +++ b/doc/w11a_os_guide.md @@ -20,24 +20,24 @@ communication between FPGA board and backend server can be via - via an integrated USB-UART bridge - on Arty, Basys3, CmodA7 and Nexys4 and Nexys4 DDR with a `FT2232HQ`, allows up to 12M Baud - - on nexys3 with a `FT232R`, allows up to 2M Baud + - on Nexys3 with a `FT232R`, allows up to 2M Baud - for all FTDI USB-UART it is essential to set them to `low latency` mode. That was default for linux kernels 2.6.32 to 4.4.52. Since about March 2017 one gets kernels with 16 ms default latency again, thanks to [kernel patch 9589541](https://patchwork.kernel.org/patch/9589541/). **For newer systems it is essential to install a udev rule** which automatically sets low latency, see [docu](../tools/sys/README.md). - - via RS232 port, as on s3board and nexys2 + - 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 + - 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 12M Baud connection, like on a nexys4, gives disk access rates and + - A 12M 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 @@ -148,7 +148,7 @@ All examples below use the same basic setup SWI = 00101100 ti_w11 -u @_boot.tcl - - for s3 serial + - for s3 over serial SWI = 00101010 ti_w11 -tu,460k,break,xon @_boot.tcl diff --git a/rtl/sys_gen/w11a/README.md b/rtl/sys_gen/w11a/README.md index bc3fea70..2c62d9f1 100644 --- a/rtl/sys_gen/w11a/README.md +++ b/rtl/sys_gen/w11a/README.md @@ -3,7 +3,7 @@ and is organized in | Directory | Content | | --------- | ------- | -| [arty_bram](arty_bram) | design for Digilent Arty, using BRAM only | +| [arty_bram](arty_bram) | design for Digilent Arty A7-35, using BRAM only | | [basys3](basys3) | design for Digilent Basys3 | | [cmoda7](cmoda7) | design for Digilent Cmod A7 (35 die size) | | [nexys2](nexys2) | design for Digilent Nexys2 | diff --git a/tools/sys/README.md b/tools/sys/README.md index 01fdacb7..02ce874c 100644 --- a/tools/sys/README.md +++ b/tools/sys/README.md @@ -4,6 +4,7 @@ This directory contains udev rule files which ensure that To setup udev rules do ```bash + cd $RETROBASE/tools/sys # !! adopt 92-retro-usb-persistent.rules to your needs !! sudo cp -a 91-retro-usb-latency.rules /etc/udev/rules.d/ sudo cp -a 92-retro-usb-persistent.rules /etc/udev/rules.d/