docs: Cleaning up some old bad links/data

Author: stffrdhrn

de0_nano/README.md de0_nano/index.mdde0_nano/README.md renamed to de0_nano/index.md

@@ -1,10 +1,15 @@
+---
+title: De0 Nano Tutorial
+layout: page
+---
+
 ## DE0 Nano Tutorial
 
 If you downloaded the tutorials as a release archive, you can directly
 start. If you have cloned the git repository, you instead need to
 follow the instructions for building the hardware and software as
 described below. Please also follow the
-[common tutorial setup](../README.md).
+[common tutorial setup](../index.html).
 
 To run the demo you need:
 

docs/Debugging.md

@@ -1,19 +1,28 @@
 ---
-title: Debugging
+title: Debugging FPGAs with OpenOCD and GDB
 layout: home
 ---
 
-## Debugging OpenRISC
+### Prerequisites
 
-The OpenRISC cpu, simulator and toolchain provide a full debugging
-environment with gdb and OpenOCD.  At a low level this is provided with
-[adv_debug_sys](https://github.com/olofk/adv_debug_sys) which provides
-jtag interface for OpenOCD to talk to.  Much can be done directly in OpenOCD. But
-for a full debug environments we recommend GDB. GDB communicates with OpenOCD as
-a remote target and provides a familiar debugging environment for programmers.
+#### Software
+
+* `or1k-elf` toolchain with gdb [Releases](https://github.com/stffrdhrn/or1k-toolchain-build/releases)
+* OpenOCD
+* A running OpenRISC SoC using `adv_debug_sys`
+
+## Debugging OpenRISC on FPGAs
+
+The OpenRISC cpu and toolchain provide a full debugging environment when running
+on FPGAs using gdb and OpenOCD.  At a low level this is provided with
+[adv_debug_sys](https://github.com/olofk/adv_debug_sys) which provides jtag
+interface for OpenOCD to talk to.  Much can be done directly in OpenOCD. But for
+a full debug environments we recommend GDB. GDB communicates with OpenOCD as a
+remote target and provides a familiar debugging environment for programmers.
 
 ### OpenOCD Basics
 
+OpenOCD is a brirdge for accessing hardware connected to a workstation via JTAG.
 OpenOCD requires a configuration file to start up.  The configuration files
 specify the chips details (jtag tap) and the details of the interface we are
 using.
@@ -75,7 +84,7 @@ reg npc 0x100
 # Resume execution after a halt
 resume
 
-# For loading a linux image you can do it all at one time. 
+# For loading a linux image you can do it all at one time.
 # Notice here we also reset r3 which linux uses as a bootargs
 # vector.
 halt; load_image vmlinux; reg r3 0; reg npc 0x100; resume
@@ -114,7 +123,12 @@ exit
 
 ### GDB Basics
 
-When we run GDB we do remote debugging
+[GDB](https://sourceware.org/gdb/) is a very popular debugger that allows
+inspecting programs running on a cpu (target).
+
+When we debug OpenRISC cpus running on FPGAs GDB connects to the remote OpenRISC
+target via the debug tcp port provided by OpenOCD.  Once OpenOCD is running we
+can start GDB as follows:
 
 ```
 # Starting up gdb (with a remote target)
@@ -264,6 +278,6 @@ These commands and further reading should get you started.
 
 ### Further Reading
 
-* http://openocd.org/doc/html/ - OpenOCD User Guide
-* http://www.fpga4fun.com/JTAG2.html - How JTAG works
-* https://sourceware.org/gdb/onlinedocs/gdb/ - Debugging with GDB
+* [OpenOCD Docs](http://openocd.org/doc/html/) - OpenOCD User Guide
+* [JTAG](http://www.fpga4fun.com/JTAG2.html) - How JTAG works
+* [GDD Docs](https://sourceware.org/gdb/onlinedocs/gdb/) - Debugging with GDB

docs/Linux.md

@@ -9,29 +9,27 @@ layout: home
 
 #### Software
 
-* Linux source code with OpenRISC patches
-* or1k-elf toolchain
+* Linux source code
+* `or1k-elf` or `or1k-linux` toolchain [Releases](https://github.com/stffrdhrn/or1k-toolchain-build/releases)
 * or1ksim (optional)
-* or1k-linux toolchain (optional)
-
-#### Files
-* Device tree file (*.dts, optional)
-* Default Linux configuration (*_defconfig, optional)
 
 ### Setting up
 
 OpenRISC is officially supported in the Linux kernel since 2011 and can be downloaded from https://www.kernel.org.
-We do however recommend that you use the kernel from https://github.com/openrisc/linux/ as it contains some convenient
-features such as a built-in initramfs and extra board configurations for OpenRISC not found in the upstream kernel.
 
 #### Get Linux source code
-git clone https://github.com/openrisc/linux
+
+```
+git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+```
 
 #### Set up Linux source code
 
+```
     cd linux
     export ARCH=openrisc
     export CROSS_COMPILE=or1k-elf-
+```
 
 The device tree file (.dts) is used to specify hardware configuration settings, such as base addresses and interrupt numbers
 for peripherals, memory sizes, the numbers of CPUs in the system and other things. If no custom device tree is used, a default one
@@ -77,5 +75,5 @@ halt; load_image vmlinux; reg r3 0; reg npc 0x100; resume
 The kernel image is now available as an elf file called `vmlinux`. This file can be used as any other bare-metal program for OpenRISC. To test the Linux image, you can:
 * Run it in the reference C simulator (or1ksim)
 * Run it on a simulated RTL model (Most likely extremely slow, unless using verilator)
-* [Load it to RAM on an FPGA board with a debugger](Debugging.md)
+* [Load it to RAM on an FPGA board with a debugger](Debugging.html)
 * Program it to non-volatile flash on an FPGA board

index.md

@@ -65,7 +65,7 @@ jtag interface for OpenOCD to talk to.  Much debugging can be done
 directly in OpenOCD.  GDB communicates with OpenOCD to provide a familiar
 debugging environment for programmers.  For more details see:
 
- * [Debugging OpenRISC](docs/Debugging.md)
+ * [Debugging OpenRISCi FPGAs with OpenOCD](docs/Debugging.html)
 
 ## Tools (partially required)