Make the doc slightly more complete and add notes on how to add a new target in OpenWrt, some serial console and JTAG tips and tricks

git-svn-id: svn://svn.openwrt.org/openwrt/trunk@13880 3c298f89-4303-0410-b956-a3cf2f4a3e73

4 files changed, 173 insertions, 3 deletions

diff --git a/docs/Makefile b/docs/Makefile
index a7fe08e505..c113d62571 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -9,7 +9,7 @@ include $(TOPDIR)/rules.mk
 include $(INCLUDE_DIR)/prereq.mk
 
 MAIN = openwrt.tex
-DEPS = $(MAIN) Makefile config.tex network.tex network-scripts.tex network-scripts.tex wireless.tex build.tex adding.tex bugs.tex $(TMP_DIR)/.prereq-docs
+DEPS = $(MAIN) Makefile config.tex network.tex network-scripts.tex network-scripts.tex wireless.tex build.tex adding.tex bugs.tex debugging.tex $(TMP_DIR)/.prereq-docs
 
 compile: $(TMP_DIR)/.prereq-docs
 	$(NO_TRACE_MAKE) cleanup
diff --git a/docs/adding.tex b/docs/adding.tex
index ec14eaec26..97547ac859 100644
--- a/docs/adding.tex
+++ b/docs/adding.tex
@@ -478,3 +478,113 @@ module_exit(device_mtd_cleanup);
 MODULE_LICENSE("GPL");
 MODULE_AUTHOR("Me, myself and I <memyselfandi@domain.tld");
 \end{verbatim}
+
+\subsection{Adding your target in OpenWrt}
+
+Once you spotted the key changes that were made to the Linux kernel
+to support your target, you will want to create a target in OpenWrt
+for your hardware. This can be useful to benefit from the toolchain
+that OpenWrt builds as well as the resulting user-space and kernel
+configuration options.
+
+Provided that your target is already known to OpenWrt, it will be
+as simple as creating a \texttt{target/linux/board} directory
+where you will be creating the following directories and files.
+
+Here for example, is a \texttt{target/linux/board/Makefile}:
+
+\begin{Verbatim}[frame=single,numbers=left]
+#
+# Copyright (C) 2009 OpenWrt.org
+#
+# This is free software, licensed under the GNU General Public License v2.
+# See /LICENSE for more information.
+#
+include $(TOPDIR)/rules.mk
+
+ARCH:=mips
+BOARD:=board
+BOARDNAME:=Eval board
+FEATURES:=squashfs jffs2 pci usb
+
+LINUX_VERSION:=2.6.27.10
+
+include $(INCLUDE_DIR)/target.mk
+
+DEFAULT_PACKAGES += hostapd-mini
+
+define Target/Description
+        Build firmware images for Evaluation board
+endef
+
+$(eval $(call BuildTarget))
+\end{Verbatim}
+
+\begin{itemize}
+    \item \texttt{ARCH} \\
+        The name of the architecture known by Linux and uClibc
+    \item \texttt{BOARD} \\
+        The name of your board that will be used as a package and build directory identifier
+    \item \texttt{BOARDNAME} \\
+        Expanded name that will appear in menuconfig
+    \item \texttt{FEATURES} \\
+        Set of features to build filesystem images, USB, PCI, VIDEO kernel support
+    \item \texttt{LINUX\_VERSION} \\
+        Linux kernel version to use for this target
+    \item \texttt{DEFAULT\_PACKAGES} \\
+        Set of packages to be built by default
+\end{itemize}
+
+A partial kernel configuration which is either named \texttt{config-default} or which matches the kernel version \texttt{config-2.6.x} should be present in \texttt{target/linux/board/}.
+This kernel configuration will only contain the relevant symbols to support your target and can be changed using \texttt{make kernel\_menuconfig}.
+
+To patch the kernel sources with the patches required to support your hardware, you will have to drop them in \texttt{patches} or in \texttt{patches-2.6.x} if there are specific
+changes between kernel versions. Additionnaly, if you want to avoid creating a patch that will create files, you can put those files into \texttt{files} or \texttt{files-2.6.x}
+with the same directory structure that the kernel uses (e.g: drivers/mtd/maps, arch/mips ..).
+
+The build system will require you to create a \texttt{target/linux/board/image/Makefile}:
+
+\begin{Verbatim}[frame=single,numbers=left]
+#
+# Copyright (C) 2009 OpenWrt.org
+#
+# This is free software, licensed under the GNU General Public License v2.
+# See /LICENSE for more information.
+#
+include $(TOPDIR)/rules.mk
+include $(INCLUDE_DIR)/image.mk
+
+define Image/BuildKernel
+        cp $(KDIR)/vmlinux.elf $(BIN_DIR)/openwrt-$(BOARD)-vmlinux.elf
+        gzip -9 -c $(KDIR)/vmlinux > $(KDIR)/vmlinux.bin.gz
+        $(STAGING_DIR_HOST)/bin/lzma e $(KDIR)/vmlinux $(KDIR)/vmlinux.bin.l7
+        dd if=$(KDIR)/vmlinux.bin.l7 of=$(BIN_DIR)/openwrt-$(BOARD)-vmlinux.lzma bs=65536 conv=sync
+        dd if=$(KDIR)/vmlinux.bin.gz of=$(BIN_DIR)/openwrt-$(BOARD)-vmlinux.gz bs=65536 conv=sync
+endef
+
+define Image/Build/squashfs
+    $(call prepare_generic_squashfs,$(KDIR)/root.squashfs)
+endef
+
+define Image/Build
+        $(call Image/Build/$(1))
+        dd if=$(KDIR)/root.$(1) of=$(BIN_DIR)/openwrt-$(BOARD)-root.$(1) bs=128k conv=sync
+
+        -$(STAGING_DIR_HOST)/bin/mkfwimage \
+                -B XS2 -v XS2.ar2316.OpenWrt \
+                -k $(BIN_DIR)/openwrt-$(BOARD)-vmlinux.lzma \
+                -r $(BIN_DIR)/openwrt-$(BOARD)-root.$(1) \
+                -o $(BIN_DIR)/openwrt-$(BOARD)-ubnt2-$(1).bin
+endef
+
+$(eval $(call BuildImage))
+
+\end{Verbatim}
+
+\begin{itemize}
+    \item \texttt{Image/BuildKernel} \\
+        This template defines changes to be made to the ELF kernel file
+    \item \texttt{Image/Build} \\
+	This template defines the final changes to apply to the rootfs and kernel, either combined or separated
+	firmware creation tools can be called here as well.
+\end{itemize}
diff --git a/docs/debugging.tex b/docs/debugging.tex
new file mode 100644
index 0000000000..2d2a5d3909
--- /dev/null
+++ b/docs/debugging.tex
@@ -0,0 +1,61 @@
+Debugging hardware can be tricky especially when doing kernel and drivers
+development. It might become handy for you to add serial console to your
+device as well as using JTAG to debug your code.
+
+\subsection{Adding a serial port}
+
+Most routers come with an UART integrated into the System-on-chip
+and its pins are routed on the Printed Circuit Board to allow
+debugging, firmware replacement or serial device connection (like
+modems).
+
+Finding an UART on a router is fairly easy since it only needs at
+least 4 signals (without modem signaling) to work : VCC, GND, TX and
+RX. Since your router is very likely to have its I/O pins working at
+3.3V (TTL level), you will need a level shifter such as a Maxim MAX232
+to change the level from 3.3V to your computer level which is usually
+at 12V.
+
+To find out the serial console pins on the PCB, you will be looking
+for a populated or unpopulated 4-pin header, which can be far from
+the SoC (signals are relatively slow) and usually with tracks on
+the top or bottom layer of the PCB, and connected to the TX and RX.
+
+Once found, you can easily check where is GND, which is connected to
+the same ground layer than the power connector. VCC should be fixed
+at 3.3V and connected to the supply layer, TX is also at 3.3V level
+but using a multimeter as an ohm-meter and showing an infinite
+value between TX and VCC pins will tell you about them being different
+signals (or not). RX and GND are by default at 0V, so using the same
+technique you can determine the remaining pins like this.
+
+If you do not have a multimeter a simple trick that usually works is
+using a speaker or a LED to determine the 3.3V signals. Additionnaly
+most PCB designer will draw a square pad to indicate ping number 1.
+
+Once found, just interface your level shifter with the device and the
+serial port on the PC on the other side. Most common baudrates for the
+off-the-shelf devices are 9600, 38400 and 115200 with 8-bits data, no
+parity, 1-bit stop.
+
+\subsection{JTAG}
+
+JTAG stands for Joint Test Action Group, which is an IEEE workgroup
+defining an electrical interface for integrated circuit testing and
+programming.
+
+There is usually a JTAG automate integrated into your System-on-Chip
+or CPU which allows an external software, controlling the JTAG adapter
+to make it perform commands like reads and writes at arbitray locations.
+Additionnaly it can be useful to recover your devices if you erased the
+bootloader resident on the flash.
+
+Different CPUs have different automates behavior and reset sequence,
+most likely you will find ARM and MIPS CPUs, both having their standard
+to allow controlling the CPU behavior using JTAG.
+
+Finding JTAG connector on a PCB can be a little easier than finding the
+UART since most vendors leave those headers unpopulated after production.
+JTAG connectors are usually 12, 14, or 20-pins headers with one side of
+the connector having some signals at 3.3V and the other side being
+connected to GND.
diff --git a/docs/openwrt.tex b/docs/openwrt.tex
index 378571711c..f6dd60fb7d 100644
--- a/docs/openwrt.tex
+++ b/docs/openwrt.tex
@@ -30,8 +30,7 @@
   \section{Adding platform support}
      \input{adding}
   \section{Debugging and debricking}
-    \subsection{Adding a serial port}
-    \subsection{JTAG}
+     \input{debugging}
    \section{Reporting bugs}
 	\subsection{Using the Trac ticket system}
 	\input{bugs}