diff options
| -rw-r--r-- | docs/Makefile | 2 | ||||
| -rw-r--r-- | docs/adding.tex | 110 | ||||
| -rw-r--r-- | docs/debugging.tex | 61 | ||||
| -rw-r--r-- | docs/openwrt.tex | 3 |
4 files changed, 173 insertions, 3 deletions
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 <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 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} |