Merge pull request #262 from mithro/docs-scripts-update

Reworking the setup documentation.

.travis/run.sh

@@ -1,6 +1,8 @@
 #!/bin/bash
 
-source scripts/setup-env.sh
+export HDMI2USB_UDEV_IGNORE=1
+
+source scripts/enter-env.sh
 
 ls -l $XILINX_DIR/opt/Xilinx/14.7/ISE_DS/ISE/bin/lin64/xreport
 if [ -f $XILINX_DIR/opt/Xilinx/14.7/ISE_DS/ISE/bin/lin64/xreport ]; then

.travis/setup.sh

@@ -19,11 +19,13 @@ fi
 GIT_REVISION=`git describe`
 echo "============================================="
 
+export HDMI2USB_UDEV_IGNORE=1
+
 # Run the script once to check it works
-time scripts/get-env.sh
+time scripts/download-env.sh
 # Run the script again to check it doesn't break things
-time scripts/get-env.sh
+time scripts/download-env.sh
 
 set +x
 set +e
-. scripts/setup-env.sh
+. scripts/enter-env.sh

Makefile

@@ -10,7 +10,9 @@ PYTHONHASHSEED := 0
 export PYTHONHASHSEED
 
 # Default board
-BOARD ?= atlys
+ifeq ($(BOARD),)
+    $(error "BOARD not set, please set it.")
+endif
 export BOARD
 # Default targets for a given board
 ifeq ($(BOARD),pipistrello)
@@ -65,6 +67,14 @@ FLASHEXTRA_CMD = \
     $(PROGRAMMER_OPTION) \
     $(BOARD)
 
+MODESWITCH_CMD = \
+  hdmi2usb-mode-switch \
+    --by-type=$(BOARD) \
+    --verbose
+
+MODEINFO_CMD = \
+  hdmi2usb-find-board \
+    --by-type=$(BOARD)
 
 ifeq ($(OS),Windows_NT)
 	FLTERM = $(PYTHON) $(MSCDIR)/tools/flterm.py
@@ -144,13 +154,23 @@ download-prebuilt:
 
 # Load
 load-gateware:
+	$(MODESWITCH_CMD) --mode=jtag
 	$(MAKEPY_CMD) load-bitstream
 
 load: load-gateware $(addprefix load-,$(TARGETS))
 	@true
 
+# FIXME: Hack to work around our dodgy FX2 firmware
+jtag-toggle:
+	$(MODESWITCH_CMD) --mode=jtag
+	sleep 1
+	$(MODESWITCH_CMD) --mode=serial
+	sleep 1
+	$(MODESWITCH_CMD) --mode=jtag
+
 # Flash
 flash-gateware: gateware-submodules
+	$(MODESWITCH_CMD) --mode=jtag
 	$(MAKEPY_CMD) flash-bitstream
 	@echo ""
 	@echo ""

Makefile.fx2

@@ -34,7 +34,7 @@ embed-fx2: firmware/lm32/fx2_fw_hdmi2usb.c
 	@true
 
 load-fx2: firmware/fx2/hdmi2usb.hex
-	firmware/fx2/download.sh firmware/fx2/hdmi2usb.hex
+	$(MODESWITCH_CMD) --load-fx2-firmware firmware/fx2/hdmi2usb.hex
 
 flash-fx2:
 	@true

Makefile.lm32

@@ -16,19 +16,15 @@ TARGETS += lm32
 
 RAM_ADDR ?= 0x20000000
 
-ifeq ($(BOARD),atlys)
-SERIAL ?= /dev/ttyVIZ0
-else
 ifeq ($(BOARD),minispartan6)
 SERIAL ?= /dev/ttyUSB1
 RAM_ADDR = 0x40000000
 else
 ifeq ($(BOARD),pipistrello)
 SERIAL ?= /dev/ttyUSB1
 else
-# Opsis fall through
-SERIAL ?= /dev/ttyACM0
-endif
+# Atlys/Opsis use modeswitch to find the serial port
+SERIAL ?= $$($(MODEINFO_CMD) --get-serial)
 endif
 endif
 
@@ -56,6 +52,7 @@ firmware-lm32: third_party/misoc/.git $(EXTRA_DEPS)
 	$(MAKE) -C firmware/lm32 all
 
 load-lm32: firmware-lm32
+	@if [ x"$(BOARD)" = x"opsis" ]; then $(MODESWITCH_CMD) --mode=serial; fi
 	@echo "To load new firmware, reboot the running firmware and then"
 	@echo "select serialboot at the BIOS prompt."
 	$(FLTERM) --port $(SERIAL) --kernel=$(HDMI2USBDIR)/firmware/lm32/firmware.bin --kernel-adr=$(RAM_ADDR) --speed 115200
@@ -70,11 +67,13 @@ flash-lm32: image-lm32
 	@echo " see https://github.com/timvideos/HDMI2USB-misoc-firmware/issues/274)"
 	@echo "Booting will use lm32 firmware embedded in the gateware."
 	@echo
+#	$(MODESWITCH_CMD) --mode=jtag
 #	export FIRMWARE_ADDRESS=$$($(PYTHON) -c "import platforms.$(BOARD) as b; print(b.Platform.gateware_size)"); \
 #	echo "Flashing to $$($(PYTHON) -c "print(hex($$FIRMWARE_ADDRESS))") ($$FIRMWARE_ADDRESS)"; \
 #	$(FLASHEXTRA_CMD) $(HDMI2USBDIR)/firmware/lm32/firmware.fbi $$FIRMWARE_ADDRESS
 
 clear-flash-lm32:
+	$(MODESWITCH_CMD) --mode=jtag
 	export FIRMWARE_ADDRESS=$$($(PYTHON) -c "import platforms.$(BOARD) as b; print(b.Platform.gateware_size)"); \
 	echo "Zeroing $$($(PYTHON) -c "print(hex($$FIRMWARE_ADDRESS))") ($$FIRMWARE_ADDRESS)"; \
 	$(FLASHEXTRA_CMD) $(HDMI2USBDIR)/firmware/zero.bin $$FIRMWARE_ADDRESS

README.md

@@ -1,14 +1,65 @@
 # HDMI2USB MiSoC Firmware
 
-#### Quick Links
+## Quick Links
 
- * [Main Repo](https://hdmi2usb.tv/firmware/)
- * [Website](https://hdmi2usb.tv/firmware-misoc)
+ * [HDMI2USB user documentation](http://hdmi2usb.tv/)
+ * [HDMI2USB Firmware documentation](https://hdmi2usb.tv/firmware-misoc)
  * [Report a bug](https://github.com/timvideos/HDMI2USB-misoc-firmware/issues/new)
  * [misoc + migen website](http://m-labs.hk/gateware.html)
 
+# Table of contents
+
+  * Overview
+  * HDMI2USB MiSoC Firmware
+    * Supported Boards
+    * Development Boards
+  * Getting started
+  * Documentation
+  * Current Status
+    * HDMI2USB
+      * Atlys
+      * Opsis
+    * HDMI2Eth
+      * Atlys
+    * Base
+      * Atlys
+      * Opsis
+      * Pipistrello
+      * miniSpartan6+
+  * License
+  * Contact
+
+# Overview
 
-### Supported Boards
+**The HDMI2USB project develops affordable hardware options to record and
+stream HD videos (from HDMI & DisplayPort sources) for conferences, meetings
+and user groups.**
+
+We are currently developing our own hardware (the
+[Numato Opsis](https://hdmi2usb.tv/numato-opsis), and also provide firmware for
+various prototyping boards.
+
+HDMI2USB started in 2013, and is an active ongoing project in its third
+iteration of hardware prototyping.  Today you can download early working
+firmware and have real capture happen, but we actively wish to improve and are
+seeking assistance:
+
+  * **For video recording individuals+teams:** Be an early adopter; get a
+    board, start using it, report back to us with feedback
+
+  * **For software/FPGA developers:** Get involved in contributing code both to
+    the capture software + FPGA stack
+
+Our aim is this becomes the defacto, incredibly affordable and easy to use
+video recording hardware for conferences, meetings and user groups worldwide.
+
+**Find out more about HDMI2USB and why we're doing this in [ABOUT + FAQ](http://hdmi2usb.tv/faq)**
+
+![HDMI2USB Diagram](https://hdmi2usb.tv/img/hdmi2usb.png "HDMI2USB Diagram")
+
+# HDMI2USB MiSoC Firmware
+
+## Supported Boards
 
 This firmware is supported on the following to boards;
 
@@ -27,7 +78,7 @@ This firmware is supported on the following to boards;
 For a comparison between the supported boards, see the 
 [HDMI2USB Hardware page](https://hdmi2usb.tv/hardware/).
 
-### Development Boards
+## Development Boards
 
  * Pipistrello - http://pipistrello.saanlima.com/
 
@@ -65,65 +116,33 @@ High level **developer** documentation for the firmware can be found in the
 
 ![System Diagram](doc/architecture.png)
 
-# License
-
-This code was original developed by [EnjoyDigital](http://enjoy-digital.fr)
-and unless otherwise noted is;
- * Copyright (C) 2015 / TimVideo.us
- * Copyright (C) 2015 / EnjoyDigital
-
-and released under a [BSD/MIT license](LICENSE). This includes the
-[gateware](gateware/), the [lm32 firmware](firmware/lm32/) and related files.
-
-The [FX2 firmware](firmware/fx2) is under the
-[GPL version 2.0 (or later)](http://www.gnu.org/licenses/gpl-2.0.en.html).
-
-Code under the [third_party](third_party/) directory comes from external
-sources and is available in their own licenses.
-
-# Contact
-
-TimVideo.us:
-
- * Mailing List:
-   * https://groups.google.com/forum/#!forum/hdmi2usb
-     [[Join](https://groups.google.com/forum/#!forum/hdmi2usb/join)]
-   * hdmi2usb@googlegroups.com
-
- * IRC:
-   * irc://irc.freenode.net/#timvideos
-     [[Web Interface](http://webchat.freenode.net/?channels=timvideos)]
-
-EnjoyDigital:
- * florent@enjoy-digital.fr
-
 # Current Status
 
-### HDMI2USB
+## HDMI2USB
 
 The `hdmi2usb` targets are for doing capturing and streaming using the FX2 USB
 interface.
 
-##### Atlys
+### Atlys
 
 [`atlys_hdmi2usb`](targets/atlys_hdmi2usb.py)
 
 * `VideomixerSoC` validated: MiniSoC + 2 x HDMI in + 2 x HDMI out
 * `HDMI2USBSoC` validated: VideomixerSoC + JPEG encoder + USB streaming
 
-##### Opsis
+### Opsis
 
 [`opsis_hdmi2usb`](targets/opsis_hdmi2usb.py)
 
 * `VideomixerSoC` validated: MiniSoC + 2 x HDMI in + 2 x HDMI out
 * `HDMI2USBSoC` validated: VideomixerSoC + JPEG encoder + USB streaming
 
-### HDMI2Eth
+## HDMI2Eth
 
 The `hdmi2eth` targets are for doing capturing and control using the Ethernet
 found on many boards.
 
-##### Atlys
+### Atlys
 
 [`atlys_hdmi2eth`](targets/atlys_hdmi2eth.py)
 
@@ -133,65 +152,66 @@ found on many boards.
 * `VideomixerSoC` validated: EtherboneSoC + HDMI in + HDMI out
 * `HDMI2ETHSoC` validated: VideomixerSoC + JPEG encoder + UDP streaming
 
-### Base
+## Base
 
 The `base` targets are used during initial bring up and verification of basic
 features. Getting MiniSoc running on new hardware is the first step towards
 supporting it. All the other, more functional, targets are built on top of this
 target.
 
-##### Atlys
+### Atlys
 
 [`atlys_base`](targets/atlys_base.py)
 
 * `BaseSoC` validated: CPU + DDR2 + UART
 * `MiniSoC` validated: BaseSoC + 10/100Mbps Ethernet MAC handled by the CPU
 
-##### Opsis
+### Opsis
 
 [`opsis_base`](targets/opsis_base.py)
 
 * `BaseSoC` validated: CPU + DDR3 + UART
 * `MiniSoC` validated: BaseSoC + 1Gbps Ethernet MAC handled by the CPU
 
-##### Pipistrello
+### Pipistrello
 
 [`pipistrello_base`](targets/pipistrello_base.py)
 
 * `BaseSoC`: CPU + LPDDR + UART
 * `VideomixerSoC`: BaseSoC + HDMI out
 
-##### miniSpartan6+
+### miniSpartan6+
 
 * `BaseSoC`: CPU + UART
 
+# License
 
+This code was original developed by [EnjoyDigital](http://enjoy-digital.fr)
+and unless otherwise noted is;
+ * Copyright (C) 2015 / TimVideo.us
+ * Copyright (C) 2015 / EnjoyDigital
 
+and released under a [BSD/MIT license](LICENSE). This includes the
+[gateware](gateware/), the [lm32 firmware](firmware/lm32/) and related files.
 
-# The HDMI2USB Project
-
-**The HDMI2USB project develops affordable hardware options to record and
-stream HD videos (from HDMI & DisplayPort sources) for conferences, meetings
-and user groups.**
-
-We are currently developing our own hardware (the 
-[Numato Opsis](https://hdmi2usb.tv/numato-opsis), and also provide firmware for
-various prototyping boards.
+The [FX2 firmware](firmware/fx2) is under the
+[GPL version 2.0 (or later)](http://www.gnu.org/licenses/gpl-2.0.en.html).
 
-HDMI2USB started in 2013, and is an active ongoing project in its third
-iteration of hardware prototyping.  Today you can download early working
-firmware and have real capture happen, but we actively wish to improve and are
-seeking assistance:
+Code under the [third_party](third_party/) directory comes from external
+sources and is available in their own licenses.
 
-  * **For video recording individuals+teams:** Be an early adopter; get a
-    board, start using it, report back to us with feedback
+# Contact
 
-  * **For software/FPGA developers:** Get involved in contributing code both to
-    the capture software + FPGA stack
+TimVideo.us:
 
-Our aim is this becomes the defacto, incredibly affordable and easy to use
-video recording hardware for conferences, meetings and user groups worldwide.
+ * Mailing List:
+   * https://groups.google.com/forum/#!forum/hdmi2usb
+     [[Join](https://groups.google.com/forum/#!forum/hdmi2usb/join)]
+   * hdmi2usb@googlegroups.com
 
-**Find out more about HDMI2USB and why we're doing this in [ABOUT + FAQ](http://hdmi2usb.tv/faq)**
+ * IRC:
+   * irc://irc.freenode.net/#timvideos
+     [[Web Interface](http://webchat.freenode.net/?channels=timvideos)]
 
-![HDMI2USB Diagram](https://hdmi2usb.tv/img/hdmi2usb.png "HDMI2USB Diagram")
+EnjoyDigital:
+ * florent@enjoy-digital.fr