From 72e15a407b5753e02413fdb158b288e3312eddfd Mon Sep 17 00:00:00 2001 From: florian Date: Tue, 6 Jan 2009 09:20:14 +0000 Subject: 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 --- docs/Makefile | 2 +- docs/adding.tex | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/debugging.tex | 61 +++++++++++++++++++++++++++++ docs/openwrt.tex | 3 +- 4 files changed, 173 insertions(+), 3 deletions(-) create mode 100644 docs/debugging.tex (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index a7fe08e50..c113d6257 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 ec14eaec2..97547ac85 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 $(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 000000000..2d2a5d390 --- /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 378571711..f6dd60fb7 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} -- cgit v1.2.3