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

SVN-Revision: 13880
This commit is contained in:
Florian Fainelli 2009-01-06 09:20:14 +00:00
parent 4df7bb3579
commit 2a25d94250
4 changed files with 173 additions and 3 deletions

View file

@ -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

View file

@ -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}

61
docs/debugging.tex Normal file
View file

@ -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.

View file

@ -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}