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}
--- /dev/null
+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.
projects / openwrt.git / commitdiff