github.com/wfjm.w11
1
0
Fork 0
mirror of https://github.com/wfjm/w11.git synced 2026-04-03 13:23:50 +00:00
Code Issues Releases Wiki Activity

minor docu updates, add INSTALL_quickstart

Browse Source
This commit is contained in:
wfjm
2018-08-04 15:07:12 +02:00
parent 6ee3ed6e85
commit 5493c0f4f2
7 changed files with 181 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

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

1
doc/CHANGELOG.md
View File

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

25
doc/INSTALL.md
View File

@@ -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)
### <a id="download">Download</a>
@@ -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 <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)
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
- `<dtype>` = `<design>`
- `<code>` = 2 letter abbreviation for the board, e.g. n4 for nexys4.
- `<btype>` = abbreviation for the board, e.g. n4 for nexys4.
### <a id="bitkits">Available bitkits with bit and log files</a>
@@ -255,6 +263,7 @@ file names contain information about release, Xlinix tool, and design:
<release>_<tool>_<design>.tgz
### <a id="fpgaconf">Configure FPGA</a>
- 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)

154
doc/INSTALL_quickstart.md Normal file
View File

@@ -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).
### <a id="prepare">Prepare</a>
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=<install-dir>
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=<install-path-of-vivado>
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).
### <a id="build">Build: generate bit file and configure FPGA</a>
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/<board>
time make sys_w11a_<btype>.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_<btype>.vconfig
### <a id="boot">Boot an operating system</a>
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/<oskit-name>
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/<oskit-name>
ti_w11 <options> @<oskit-name>_boot.tcl
Hit <ENTER> 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.
### <a id="tested">Concrete test run</a>
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 <ENTER> 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
: {<CR>}
: 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`.

10
doc/w11a_os_guide.md
View File

@@ -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 @<oskit-name>_boot.tcl
- for s3 serial
- for s3 over serial
SWI = 00101010
ti_w11 -tu<dn>,460k,break,xon @<oskit-name>_boot.tcl

2
rtl/sys_gen/w11a/README.md
View File

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

1
tools/sys/README.md
View File

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