diff --git a/README.md b/README.md
index 383e3663..93532296 100644
--- a/README.md
+++ b/README.md
@@ -13,14 +13,27 @@ 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 project [home page](https://wfjm.github.io/home/w11/)
+ and [blog](https://wfjm.github.io/blogs/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 operating systems](doc/w11a_os_guide.md)
-- [known issues general](doc/README_known_issues.md)
-- [known issues w11a CPU](doc/w11a_known_issues.md)
+ and [installation notes](doc/INSTALL.md)
+- guides to build bit files and test benches
+ with [Xilinx Vivado](doc/README_buildsystem_Vivado.md.html)
+ and [Xilinx ISE](doc/README_buildsystem_ISE.md.html)
+- guides to [run test benches](doc/w11a_tb_guide.md)
+ 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)
+
+A short description of the directory layout
+[is provided separately](https://wfjm.github.io/home/w11/impl/dirlayout.html),
+the top level directories are
+
+| Directory | Content |
+| --------- | ------- |
+| [doc](doc) | documentation |
+| [rtl](rtl) | HDL sources (mostly vhdl) |
+| [tools](tools) | many tools |
### Note on freecores/w11
The [freecores team](http://freecores.github.io/) created in 2014 a
diff --git a/doc/CHANGELOG.md b/doc/CHANGELOG.md
index ebd59d32..b89a7763 100644
--- a/doc/CHANGELOG.md
+++ b/doc/CHANGELOG.md
@@ -1,16 +1,23 @@
-# Changelog: w11a_V0.74 -> master
+# Changelog: w11a_V0.74 -> HEAD
### Table of contents
-- Current [master](#user-content-master)
-
+- Current [HEAD](#user-content-head)
+- 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)
- [CHANGELOG for w11a_V.60 to w11a_V0.70](CHANGELOG-w11a_V0.60-w11a_V0.70.md)
- [CHANGELOG for w11a_V.50 to w11a_V0.60](CHANGELOG-w11a_V0.50-w11a_V0.60.md)
---
-## master
+## HEAD
+
+---
+## 2016-12-23: w11a_V0.741 - rev 826(wfjm)
### Summary
-- converted documentation from plain text to markdown
-
+- moved w11 repository from OpenCores to GitHub
+ [wfjm/w11](https://github.com/wfjm/w11/)
+- moved w11 project pages from OpenCores to GitHub-Pages
+ [wfjm.github.io/home/w11](https://wfjm.github.io/home/w11/)
+- converted existing documentation from plain text to markdown
+- added README.md files
diff --git a/doc/w11a_known_issues.md b/doc/w11a_known_issues.md
index dffa70ff..0f5e60b0 100644
--- a/doc/w11a_known_issues.md
+++ b/doc/w11a_known_issues.md
@@ -13,19 +13,23 @@ This file descibes issues of the w11 CPU.
### Known differences between w11a and KB11-C (11/70)
-- the SPL instruction in the 11/70 always fetched the next instruction
+- 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
+ as the infamous _spl bug_, see
+ - http://minnie.tuhs.org/pipermail/tuhs/2006-September/001086.html
+ - http://minnie.tuhs.org/pipermail/tuhs/2006-October/001087.html
+ - http://minnie.tuhs.org/pipermail/tuhs/2006-October/001088.html
+ - http://minnie.tuhs.org/pipermail/tuhs/2006-October/001089.html
+ - http://minnie.tuhs.org/pipermail/tuhs/2006-October/001095.html
+ - http://minnie.tuhs.org/pipermail/tuhs/2006-October/001096.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.
+ 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
+ `NOOP`, 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
+- 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.
@@ -37,7 +41,7 @@ This file descibes issues of the w11 CPU.
All four points relate to very 11/70 specific behaviour, no operating system
depends on them, therefore they are considered acceptable implementation
-differences
+differences.
### Known limitations
@@ -96,5 +100,5 @@ 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**
+ - **TCK-003 pri=H: CPU: yel-stack by `IOT` pushes two stack frames**
diff --git a/rtl/README.md b/rtl/README.md
new file mode 100644
index 00000000..8d74b2c8
--- /dev/null
+++ b/rtl/README.md
@@ -0,0 +1,11 @@
+This directory tree contains all **HDL sources** and is organized in
+
+| Directory | Content |
+| --------- | ------- |
+| [bplib](bplib) | support modules for boards or parts |
+| [ibus](ibus) | w11 ibus devices |
+| [make_ise](make_ise) | make includes for ISE build flows |
+| [make_viv](make_viv) | make includes for Vivado build flows |
+| [sys_gen](sys_gen) | HDL sources for top level designs |
+| [vlib](vlib) | wide range of support modules |
+| [w11a](w11a) | HDL sources for w11a core |
diff --git a/rtl/bplib/README.md b/rtl/bplib/README.md
new file mode 100644
index 00000000..466beecf
--- /dev/null
+++ b/rtl/bplib/README.md
@@ -0,0 +1,19 @@
+This directory sub-tree contains **support modules for boards or parts**
+and is organized in
+
+| Directory | Content |
+| --------- | ------- |
+| [arty](arty) | support for Digilent Arty board |
+| [atlys](atlys) | support for Digilent Atlys board |
+| [basys3](basys3) | support for Digilent Basys3 board |
+| [bpgen](bpgen) | interfaces for IO devices common on Digilent boards |
+| [fx2lib](fx2lib) | interface for Cypress FX2 USB |
+| [fx2rlink](fx2rlink) | modules for rlink over Cypress FX2 |
+| [issi](issi) | simulation models for ISSI components |
+| [micron](micron) | simulation models for Micron components |
+| [nexys2](nexys2) | support for Digilent Nexys2 board |
+| [nexys3](nexys3) | support for Digilent Nexys3 board |
+| [nexys4](nexys4) | support for Digilent Nexys4 board (cram version) |
+| [nxcramlib](nxcramlib) | interface for ISSI CRAM |
+| [s3board](s3board) | support for Digilent S3BOARD board |
+| [sysmon](sysmon) | interface for Xilinx Series-7 sysmon |
diff --git a/rtl/sys_gen/README.md b/rtl/sys_gen/README.md
new file mode 100644
index 00000000..87efa800
--- /dev/null
+++ b/rtl/sys_gen/README.md
@@ -0,0 +1,11 @@
+This directory sub-tree contains **HDL sources for top level designs**
+and is organized in
+
+| Directory | Content |
+| --------- | ------- |
+| [tst_rlink](tst_rlink) | rlink tester (over serial links) |
+| [tst_rlink_cuff](tst_rlink_cuff) | rlink tester (over Cypress FX2 USB) |
+| [tst_serloop](tst_serloop) | serial port loop back tester |
+| [tst_snhumanio](tst_snhumanio) | Digilent board human IO tester |
+| [tst_sram](tst_sram) | memory tester (SRAM or CRAM) |
+| [w11a](w11a) | w11a systems |
diff --git a/rtl/vlib/README.md b/rtl/vlib/README.md
new file mode 100644
index 00000000..deff1547
--- /dev/null
+++ b/rtl/vlib/README.md
@@ -0,0 +1,14 @@
+This directory sub-tree contains **a wide range of support modules**
+and is organized in
+
+| Directory | Content |
+| --------- | ------- |
+| [cdclib](cdclib) | modules for clock domain crossing |
+| [comlib](comlib) | modules for communication |
+| [genlib](genlib) | grab bag of other modules |
+| [memlib](memlib) | wrappers for distributed and block RAM; fifos |
+| [rbus](rbus) | modules for rbus fabric; some basic rbus devices |
+| [rlink](rlink) | rlink interface |
+| [serport](serport) | serial port interface |
+| [simlib](simlib) | helper modules for test benches |
+| [xlib](xlib) | warppers for some Xilinx components |
diff --git a/tools/README.md b/tools/README.md
new file mode 100644
index 00000000..539139bb
--- /dev/null
+++ b/tools/README.md
@@ -0,0 +1,16 @@
+This directory tree contains **many tools** and is organized in
+
+| Directory | Content |
+| --------- | ------- |
+| [asm-11](asm-11) | environment for `asm-11` assembler |
+| [bin](bin) | support scripts and tools |
+| [dox](dox) | configuration files for Doxygen |
+| [fx2](fx2) | firmware for Cypress FX2 USB interface |
+| [make](make) | make includes |
+| [man](man) | man pages |
+| [oskit](oskit) | support files for OS disk/tape image kits |
+| [simh](simh) | configuration files for `simh pdp11` |
+| [src](src) | C++ sources for rlink backend |
+| [tbench](tbench) | w11 test bench |
+| [tcl](tcl) | TCL sources for rlink backend |
+| [vivado](vivado) | scripts for Xilinx Vivado |
diff --git a/tools/fx2/README.md b/tools/fx2/README.md
new file mode 100644
index 00000000..e42df7c0
--- /dev/null
+++ b/tools/fx2/README.md
@@ -0,0 +1,8 @@
+This directory tree contains **firmware for Cypress FX2 USB interface**
+and is organized in
+
+| Directory | Content |
+| --------- | ------- |
+| [bin](bin) | ready to load binaries (in Intel hex format) |
+| [src](src) | sources for firmware |
+| [sys](sys) | udev rules FX2 access |
diff --git a/tools/fx2/src/README.md b/tools/fx2/src/README.md
index e52feb34..def65111 100644
--- a/tools/fx2/src/README.md
+++ b/tools/fx2/src/README.md
@@ -1,10 +1,10 @@
-The FX2 software is based on the Sourceforge project ixo-jtag
+The FX2 firmware is based on the Sourceforge project `ixo-jtag`
http://sourceforge.net/projects/ixo-jtag/
-The usb_jtag sub project was checked out on 2011-07-17 (Rev 204) from
+The `usb_jtag` sub project was checked out on 2011-07-17 (Rev 204) from
Sourceforge and taken as basis for the further developement.
-The original README.txt is preserved under
+The original `README.txt` is preserved under
[README_iso_jtag.txt](README_iso_jtag.txt).
Only the `hw_nexys.c` branch was kept on the import.
diff --git a/tools/src/README.md b/tools/src/README.md
new file mode 100644
index 00000000..25e0e0ae
--- /dev/null
+++ b/tools/src/README.md
@@ -0,0 +1,14 @@
+This directory tree contains **C++ sources for rlink backend**
+and is organized in
+
+| Directory | Content |
+| --------- | ------- |
+| [librlink](librlink) | rlink core library |
+| [librlinktpp](librlinktpp) | tcl wrapper for rlink core library |
+| [librtcltools](librtcltools) | support classes for tcl wrappers |
+| [librtools](librtools) | support classes |
+| [librutiltpp](librutiltpp) | some custom tcl commands |
+| [librw11](librw11) | w11 backend library |
+| [librwxxtpp](librwxxtpp) | tcl wrapper for w11 backend library |
+| [tclshcpp](tclshcpp) | custom tcl shell |
+| [testtclsh](testtclsh) | statically linked custom tcl shell |