docs: deleting docs because they are obsolete
the docs in /docs folder are pretty much obsolete and in a not very friendly format (latex, that requires to be compiled), leaving them there only causes confusion. LEDE documentation's place is the wiki, or the site. Signed-off-by: Alberto Bursi <alberto.bursi@outlook.it>
This commit is contained in:
Alberto Bursi
John Crispin
parent
c0e66478b5
commit
882f4d2d63
15 changed files with 0 additions and 2515 deletions
15
docs/.gitignore
vendored
15
docs/.gitignore
vendored
|
|
@ -1,15 +0,0 @@
|
||||||
*.log
|
|
||||||
*.aux
|
|
||||||
*.toc
|
|
||||||
*.out
|
|
||||||
*.lg
|
|
||||||
*.dvi
|
|
||||||
*.idv
|
|
||||||
*.4ct
|
|
||||||
*.4tc
|
|
||||||
*.xref
|
|
||||||
*.tmp
|
|
||||||
*.dvi
|
|
||||||
*.html
|
|
||||||
*.css
|
|
||||||
*.pdf
|
|
||||||
|
|
@ -1,48 +0,0 @@
|
||||||
ifeq ($(TOPDIR),)
|
|
||||||
TOPDIR:=${CURDIR}/..
|
|
||||||
endif
|
|
||||||
PKG_NAME=docs
|
|
||||||
|
|
||||||
all: compile
|
|
||||||
|
|
||||||
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 debugging.tex $(TMP_DIR)/.prereq-docs
|
|
||||||
|
|
||||||
compile: $(TMP_DIR)/.prereq-docs
|
|
||||||
$(NO_TRACE_MAKE) cleanup
|
|
||||||
latex $(MAIN)
|
|
||||||
$(NO_TRACE_MAKE) openwrt.pdf openwrt.html
|
|
||||||
$(NO_TRACE_MAKE) cleanup
|
|
||||||
|
|
||||||
$(TMP_DIR)/.prereq-docs:
|
|
||||||
mkdir -p $(TMP_DIR)
|
|
||||||
$(NO_TRACE_MAKE) prereq
|
|
||||||
touch $@
|
|
||||||
|
|
||||||
openwrt.html: $(DEPS)
|
|
||||||
htlatex $(MAIN)
|
|
||||||
|
|
||||||
openwrt.pdf: $(DEPS)
|
|
||||||
pdflatex $(MAIN)
|
|
||||||
|
|
||||||
clean: cleanup
|
|
||||||
rm -f openwrt.pdf openwrt.html openwrt.css
|
|
||||||
|
|
||||||
cleanup: FORCE
|
|
||||||
rm -f *.log *.aux *.toc *.out *.lg *.dvi *.idv *.4ct *.4tc *.xref *.tmp *.dvi
|
|
||||||
|
|
||||||
$(eval $(call RequireCommand,latex, \
|
|
||||||
You need to install LaTeX to build the OpenWrt documentation \
|
|
||||||
))
|
|
||||||
$(eval $(call RequireCommand,pdflatex, \
|
|
||||||
You need to install PDFLaTeX to build the OpenWrt documentation \
|
|
||||||
))
|
|
||||||
$(eval $(call RequireCommand,htlatex, \
|
|
||||||
You need to install tex4ht to build the OpenWrt documentation \
|
|
||||||
))
|
|
||||||
|
|
||||||
FORCE:
|
|
||||||
.PHONY: FORCE
|
|
||||||
590
docs/adding.tex
590
docs/adding.tex
|
|
@ -1,590 +0,0 @@
|
||||||
Linux is now one of the most widespread operating system for embedded devices due
|
|
||||||
to its openess as well as the wide variety of platforms it can run on. Many
|
|
||||||
manufacturer actually use it in firmware you can find on many devices: DVB-T
|
|
||||||
decoders, routers, print servers, DVD players ... Most of the time the stock
|
|
||||||
firmware is not really open to the consumer, even if it uses open source software.
|
|
||||||
|
|
||||||
You might be interested in running a Linux based firmware for your router for
|
|
||||||
various reasons: extending the use of a network protocol (such as IPv6), having
|
|
||||||
new features, new piece of software inside, or for security reasons. A fully
|
|
||||||
open-source firmware is de-facto needed for such applications, since you want to
|
|
||||||
be free to use this or that version of a particular reason, be able to correct a
|
|
||||||
particular bug. Few manufacturers do ship their routers with a Sample Development Kit,
|
|
||||||
that would allow you to create your own and custom firmware and most of the time,
|
|
||||||
when they do, you will most likely not be able to complete the firmware creation process.
|
|
||||||
|
|
||||||
This is one of the reasons why OpenWrt and other firmware exists: providing a
|
|
||||||
version independent, and tools independent firmware, that can be run on various
|
|
||||||
platforms, known to be running Linux originally.
|
|
||||||
|
|
||||||
\subsection{Which Operating System does this device run?}
|
|
||||||
|
|
||||||
There is a lot of methods to ensure your device is running Linux. Some of them do
|
|
||||||
need your router to be unscrewed and open, some can be done by probing the device
|
|
||||||
using its external network interfaces.
|
|
||||||
|
|
||||||
\subsubsection{Operating System fingerprinting and port scanning}
|
|
||||||
|
|
||||||
A large bunch of tools over the Internet exists in order to let you do OS
|
|
||||||
fingerprinting, we will show here an example using \textbf{nmap}:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
nmap -P0 -O <IP address>
|
|
||||||
Starting Nmap 4.20 ( http://insecure.org ) at 2007-01-08 11:05 CET
|
|
||||||
Interesting ports on 192.168.2.1:
|
|
||||||
Not shown: 1693 closed ports
|
|
||||||
PORT STATE SERVICE
|
|
||||||
22/tcp open ssh
|
|
||||||
23/tcp open telnet
|
|
||||||
53/tcp open domain
|
|
||||||
80/tcp open http
|
|
||||||
MAC Address: 00:13:xx:xx:xx:xx (Cisco-Linksys)
|
|
||||||
Device type: broadband router
|
|
||||||
Running: Linksys embedded
|
|
||||||
OS details: Linksys WRT54GS v4 running OpenWrt w/Linux kernel 2.4.30
|
|
||||||
Network Distance: 1 hop
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
nmap is able to report whether your device uses a Linux TCP/IP stack, and if so,
|
|
||||||
will show you which Linux kernel version is probably runs. This report is quite
|
|
||||||
reliable and it can make the distinction between BSD and Linux TCP/IP stacks and others.
|
|
||||||
|
|
||||||
Using the same tool, you can also do port scanning and service version discovery.
|
|
||||||
For instance, the following command will report which IP-based services are running
|
|
||||||
on the device, and which version of the service is being used:
|
|
||||||
|
|
||||||
\begin{verbatim}
|
|
||||||
nmap -P0 -sV <IP address>
|
|
||||||
Starting Nmap 4.20 ( http://insecure.org ) at 2007-01-08 11:06 CET
|
|
||||||
Interesting ports on 192.168.2.1:
|
|
||||||
Not shown: 1693 closed ports
|
|
||||||
PORT STATE SERVICE VERSION
|
|
||||||
22/tcp open ssh Dropbear sshd 0.48 (protocol 2.0)
|
|
||||||
23/tcp open telnet Busybox telnetd
|
|
||||||
53/tcp open domain ISC Bind dnsmasq-2.35
|
|
||||||
80/tcp open http OpenWrt BusyBox httpd
|
|
||||||
MAC Address: 00:13:xx:xx:xx:xx (Cisco-Linksys)
|
|
||||||
Service Info: Device: WAP
|
|
||||||
\end{verbatim}
|
|
||||||
|
|
||||||
The web server version, if identified, can be determining in knowing the Operating
|
|
||||||
System. For instance, the \textbf{BOA} web server is typical from devices running
|
|
||||||
an open-source Unix or Unix-like.
|
|
||||||
|
|
||||||
\subsubsection{Wireless Communications Fingerprinting}
|
|
||||||
|
|
||||||
Although this method is not really known and widespread, using a wireless scanner
|
|
||||||
to discover which OS your router or Access Point run can be used. We do not have
|
|
||||||
a clear example of how this could be achieved, but you will have to monitor raw
|
|
||||||
802.11 frames and compare them to a very similar device running a Linux based firmware.
|
|
||||||
|
|
||||||
\subsubsection{Web server security exploits}
|
|
||||||
|
|
||||||
The Linksys WRT54G was originally hacked by using a "ping bug" discovered in the
|
|
||||||
web interface. This tip has not been fixed for months by Linksys, allowing people
|
|
||||||
to enable the "boot\_wait" helper process via the web interface. Many web servers
|
|
||||||
used in firmwares are open source web server, thus allowing the code to be audited
|
|
||||||
to find an exploit. Once you know the web server version that runs on your device,
|
|
||||||
by using \textbf{nmap -sV} or so, you might be interested in using exploits to reach
|
|
||||||
shell access on your device.
|
|
||||||
|
|
||||||
\subsubsection{Native Telnet/SSH access}
|
|
||||||
|
|
||||||
Some firmwares might have restricted or unrestricted Telnet/SSH access, if so,
|
|
||||||
try to log in with the web interface login/password and see if you can type in
|
|
||||||
some commands. This is actually the case for some Broadcom BCM963xx based firmwares
|
|
||||||
such as the one in Neuf/Cegetel ISP routers, Club-Internet ISP CI-Box and many
|
|
||||||
others. Some commands, like \textbf{cat} might be left here and be used to
|
|
||||||
determine the Linux kernel version.
|
|
||||||
|
|
||||||
\subsubsection{Analysing a binary firmware image}
|
|
||||||
|
|
||||||
You are very likely to find a firmware binary image on the manufacturer website,
|
|
||||||
even if your device runs a proprietary operating system. If so, you can download
|
|
||||||
it and use an hexadecimal editor to find printable words such as \textbf{vmlinux},
|
|
||||||
\textbf{linux}, \textbf{ramdisk}, \textbf{mtd} and others.
|
|
||||||
|
|
||||||
Some Unix tools like \textbf{hexdump} or \textbf{strings} can be used to analyse
|
|
||||||
the firmware. Below there is an example with a binary firmware found other the Internet:
|
|
||||||
|
|
||||||
\begin{verbatim}
|
|
||||||
hexdump -C <binary image.extension> | less (more)
|
|
||||||
00000000 46 49 52 45 32 2e 35 2e 30 00 00 00 00 00 00 00 |FIRE2.5.0.......|
|
|
||||||
00000010 00 00 00 00 31 2e 30 2e 30 00 00 00 00 00 00 00 |....1.0.0.......|
|
|
||||||
00000020 00 00 00 00 00 00 00 38 00 43 36 29 00 0a e6 dc |.......8.C6)..??|
|
|
||||||
00000030 54 49 44 45 92 89 54 66 1f 8b 08 08 f8 10 68 42 |TIDE..Tf....?.hB|
|
|
||||||
00000040 02 03 72 61 6d 64 69 73 6b 00 ec 7d 09 bc d5 d3 |..ramdisk.?}.???|
|
|
||||||
00000050 da ff f3 9b f7 39 7b ef 73 f6 19 3b 53 67 ea 44 |???.?9{?s?.;Sg?D|
|
|
||||||
\end{verbatim}
|
|
||||||
|
|
||||||
Scroll over the firmware to find printable words that can be significant.
|
|
||||||
|
|
||||||
\subsubsection{Amount of flash memory}
|
|
||||||
|
|
||||||
Linux can hardly fit in a 2MB flash device, once you have opened the device and
|
|
||||||
located the flash chip, try to find its characteristics on the Internet. If
|
|
||||||
your flash chip is a 2MB or less device, your device is most likely to run a
|
|
||||||
proprietary OS such as WindRiver VxWorks, or a custom manufacturer OS like Zyxel ZynOS.
|
|
||||||
|
|
||||||
OpenWrt does not currently run on devices which have 2MB or less of flash memory.
|
|
||||||
This limitation will probably not be worked around since those devices are most
|
|
||||||
of the time micro-routers, or Wireless Access Points, which are not the main
|
|
||||||
OpenWrt target.
|
|
||||||
|
|
||||||
\subsubsection{Pluging a serial port}
|
|
||||||
|
|
||||||
By using a serial port and a level shifter, you may reach the console that is being shown by the device
|
|
||||||
for debugging or flashing purposes. By analysing the output of this device, you can
|
|
||||||
easily notice if the device uses a Linux kernel or something different.
|
|
||||||
|
|
||||||
\subsection{Finding and using the manufacturer SDK}
|
|
||||||
|
|
||||||
Once you are sure your device run a Linux based firmware, you will be able to start
|
|
||||||
hacking on it. If the manufacturer respected the GPL, it will have released a Sample
|
|
||||||
Development Kit with the device.
|
|
||||||
|
|
||||||
\subsubsection{GPL violations}
|
|
||||||
|
|
||||||
Some manufacturers do release a Linux based binary firmware, with no sources at all.
|
|
||||||
The first step before doing anything is to read the license coming with your device,
|
|
||||||
then write them about this lack of Open Source code. If the manufacturer answers
|
|
||||||
you they do not have to release a SDK containing Open Source software, then we
|
|
||||||
recommend you get in touch with the gpl-violations.org community.
|
|
||||||
|
|
||||||
You will find below a sample letter that can be sent to the manufacturer:
|
|
||||||
|
|
||||||
\begin{verse}
|
|
||||||
Miss, Mister,
|
|
||||||
|
|
||||||
I am using a <device name>, and I cannot find neither on your website nor on the
|
|
||||||
CD-ROM the open source software used to build or modify the firmware.
|
|
||||||
|
|
||||||
In conformance to the GPL license, you have to release the following sources:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item complete toolchain that made the kernel and applications be compiled (gcc, binutils, libc)
|
|
||||||
\item tools to build a custom firmware (mksquashfs, mkcramfs ...)
|
|
||||||
\item kernel sources with patches to make it run on this specific hardware, this does not include binary drivers
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
Thank you very much in advance for your answer.
|
|
||||||
|
|
||||||
Best regards, <your name>
|
|
||||||
\end{verse}
|
|
||||||
|
|
||||||
\subsubsection{Using the SDK}
|
|
||||||
|
|
||||||
Once the SDK is available, you are most likely not to be able to build a complete
|
|
||||||
or functional firmware using it, but parts of it, like only the kernel, or only
|
|
||||||
the root filesystem. Most manufacturers do not really care releasing a tool that
|
|
||||||
do work every time you uncompress and use it.
|
|
||||||
|
|
||||||
You should anyway be able to use the following components:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item kernel sources with more or less functional patches for your hardware
|
|
||||||
\item binary drivers linked or to be linked with the shipped kernel version
|
|
||||||
\item packages of the toolchain used to compile the whole firmware: gcc, binutils, libc or uClibc
|
|
||||||
\item binary tools to create a valid firmware image
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
Your work can be divided into the following tasks:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item create a clean patch of the hardware specific part of the linux kernel
|
|
||||||
\item spot potential kernel GPL violations especially on netfilter and USB stack stuff
|
|
||||||
\item make the binary drivers work, until there are open source drivers
|
|
||||||
\item use standard a GNU toolchain to make working executables
|
|
||||||
\item understand and write open source tools to generate a valid firmware image
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\subsubsection{Creating a hardware specific kernel patch}
|
|
||||||
|
|
||||||
Most of the time, the kernel source that comes along with the SDK is not really
|
|
||||||
clean, and is not a standard Linux version, it also has architecture specific
|
|
||||||
fixes backported from the \textbf{CVS} or the \textbf{git} repository of the
|
|
||||||
kernel development trees. Anyway, some parts can be easily isolated and used as
|
|
||||||
a good start to make a vanilla kernel work your hardware.
|
|
||||||
|
|
||||||
Some directories are very likely to have local modifications needed to make your
|
|
||||||
hardware be recognized and used under Linux. First of all, you need to find out
|
|
||||||
the linux kernel version that is used by your hardware, this can be found by
|
|
||||||
editing the \textbf{linux/Makefile} file.
|
|
||||||
|
|
||||||
\begin{verbatim}
|
|
||||||
head -5 linux-2.x.x/Makefile
|
|
||||||
VERSION = 2
|
|
||||||
PATCHLEVEL = x
|
|
||||||
SUBLEVEL = y
|
|
||||||
EXTRAVERSION = z
|
|
||||||
NAME=A fancy name
|
|
||||||
\end{verbatim}
|
|
||||||
|
|
||||||
So now, you know that you have to download a standard kernel tarball at
|
|
||||||
\textbf{kernel.org} that matches the version being used by your hardware.
|
|
||||||
|
|
||||||
Then you can create a \textbf{diff} file between the two trees, especially for the
|
|
||||||
following directories:
|
|
||||||
|
|
||||||
\begin{verbatim}
|
|
||||||
diff -urN linux-2.x.x/arch/<sub architecture> linux-2.x.x-modified/arch/<sub architecture> > 01-architecture.patch
|
|
||||||
diff -urN linux-2.x.x/include/ linux-2.x.x-modified/include > 02-includes.patch
|
|
||||||
diff -urN linux-2.x.x/drivers/ linux-2.x.x-modified/drivers > 03-drivers.patch
|
|
||||||
\end{verbatim}
|
|
||||||
|
|
||||||
This will constitute a basic set of three patches that are very likely to contain
|
|
||||||
any needed modifications that has been made to the stock Linux kernel to run on
|
|
||||||
your specific device. Of course, the content produced by the \textbf{diff -urN}
|
|
||||||
may not always be relevant, so that you have to clean up those patches to only
|
|
||||||
let the "must have" code into them.
|
|
||||||
|
|
||||||
The first patch will contain all the code that is needed by the board to be
|
|
||||||
initialized at startup, as well as processor detection and other boot time
|
|
||||||
specific fixes.
|
|
||||||
|
|
||||||
The second patch will contain all useful definitions for that board: addresses,
|
|
||||||
kernel granularity, redefinitions, processor family and features ...
|
|
||||||
|
|
||||||
The third patch may contain drivers for: serial console, ethernet NIC, wireless
|
|
||||||
NIC, USB NIC ... Most of the time this patch contains nothing else than "glue"
|
|
||||||
code that has been added to make the binary driver work with the Linux kernel.
|
|
||||||
This code might not be useful if you plan on writing drivers from scratch for
|
|
||||||
this hardware.
|
|
||||||
|
|
||||||
\subsubsection{Using the device bootloader}
|
|
||||||
|
|
||||||
The bootloader is the first program that is started right after your device has
|
|
||||||
been powered on. This program, can be more or less sophisticated, some do let you
|
|
||||||
do network booting, USB mass storage booting ... The bootloader is device and
|
|
||||||
architecture specific, some bootloaders were designed to be universal such as
|
|
||||||
RedBoot or U-Boot so that you can meet those loaders on totally different
|
|
||||||
platforms and expect them to behave the same way.
|
|
||||||
|
|
||||||
If your device runs a proprietary operating system, you are very likely to deal
|
|
||||||
with a proprietary boot loader as well. This may not always be a limitation,
|
|
||||||
some proprietary bootloaders can even have source code available (i.e : Broadcom CFE).
|
|
||||||
|
|
||||||
According to the bootloader features, hacking on the device will be more or less
|
|
||||||
easier. It is very probable that the bootloader, even exotic and rare, has a
|
|
||||||
documentation somewhere over the Internet. In order to know what will be possible
|
|
||||||
with your bootloader and the way you are going to hack the device, look over the
|
|
||||||
following features :
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item does the bootloader allow net booting via bootp/DHCP/NFS or tftp
|
|
||||||
\item does the bootloader accept loading ELF binaries ?
|
|
||||||
\item does the bootloader have a kernel/firmware size limitation ?
|
|
||||||
\item does the bootloader expect a firmware format to be loaded with ?
|
|
||||||
\item are the loaded files executed from RAM or flash ?
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
Net booting is something very convenient, because you will only have to set up network
|
|
||||||
booting servers on your development station, and keep the original firmware on the device
|
|
||||||
till you are sure you can replace it. This also prevents your device from being flashed,
|
|
||||||
and potentially bricked every time you want to test a modification on the kernel/filesystem.
|
|
||||||
|
|
||||||
If your device needs to be flashed every time you load a firmware, the bootlader might
|
|
||||||
only accept a specific firmware format to be loaded, so that you will have to
|
|
||||||
understand the firmware format as well.
|
|
||||||
|
|
||||||
\subsubsection{Making binary drivers work}
|
|
||||||
|
|
||||||
As we have explained before, manufacturers do release binary drivers in their GPL
|
|
||||||
tarball. When those drivers are statically linked into the kernel, they become GPL
|
|
||||||
as well, fortunately or unfortunately, most of the drivers are not statically linked.
|
|
||||||
This anyway lets you a chance to dynamically link the driver with the current kernel
|
|
||||||
version, and try to make them work together.
|
|
||||||
|
|
||||||
This is one of the most tricky and grey part of the fully open source projects.
|
|
||||||
Some drivers require few modifications to be working with your custom kernel,
|
|
||||||
because they worked with an earlier kernel, and few modifications have been made
|
|
||||||
to the kernel in-between those versions. This is for instance the case with the
|
|
||||||
binary driver of the Broadcom BCM43xx Wireless Chipsets, where only few differences
|
|
||||||
were made to the network interface structures.
|
|
||||||
|
|
||||||
Some general principles can be applied no matter which kernel version is used in
|
|
||||||
order to make binary drivers work with your custom kernel:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item turn on kernel debugging features such as:
|
|
||||||
\begin{itemize}
|
|
||||||
\item CONFIG\_DEBUG\_KERNEL
|
|
||||||
\item CONFIG\_DETECT\_SOFTLOCKUP
|
|
||||||
\item CONFIG\_DEBUG\_KOBJECT
|
|
||||||
\item CONFIG\_KALLSYMS
|
|
||||||
\item CONFIG\_KALLSYMS\_ALL
|
|
||||||
\end{itemize}
|
|
||||||
\item link binary drivers when possible to the current kernel version
|
|
||||||
\item try to load those binary drivers
|
|
||||||
\item catch the lockups and understand them
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
Most of the time, loading binary drivers will fail, and generate a kernel oops.
|
|
||||||
You can know the last symbol the binary drivers attempted to use, and see in the
|
|
||||||
kernel headers file, if you do not have to move some structures field before or
|
|
||||||
after that symbol in order to keep compatibily with both the binary driver and
|
|
||||||
the stock kernel drivers.
|
|
||||||
|
|
||||||
\subsubsection{Understanding the firmware format}
|
|
||||||
|
|
||||||
You might want to understand the firmware format, even if you are not yet capable
|
|
||||||
of running a custom firmware on your device, because this is sometimes a blocking
|
|
||||||
part of the flashing process.
|
|
||||||
|
|
||||||
A firmware format is most of the time composed of the following fields:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item header, containing a firmware version and additional fields: Vendor, Hardware version ...
|
|
||||||
\item CRC32 checksum on either the whole file or just part of it
|
|
||||||
\item Binary and/or compressed kernel image
|
|
||||||
\item Binary and/or compressed root filesystem image
|
|
||||||
\item potential garbage
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
Once you have figured out how the firmware format is partitioned, you will have
|
|
||||||
to write your own tool that produces valid firmware binaries. One thing to be very
|
|
||||||
careful here is the endianness of either the machine that produces the binary
|
|
||||||
firmware and the device that will be flashed using this binary firmware.
|
|
||||||
|
|
||||||
\subsubsection{Writing a flash map driver}
|
|
||||||
|
|
||||||
The flash map driver has an important role in making your custom firmware work
|
|
||||||
because it is responsible of mapping the correct flash regions and associated
|
|
||||||
rights to specific parts of the system such as: bootloader, kernel, user filesystem.
|
|
||||||
|
|
||||||
Writing your own flash map driver is not really a hard task once you know how your
|
|
||||||
firmware image and flash is structured. You will find below a commented example
|
|
||||||
that covers the case of the device where the bootloader can pass to the kernel its partition plan.
|
|
||||||
|
|
||||||
First of all, you need to make your flash map driver be visible in the kernel
|
|
||||||
configuration options, this can be done by editing the file \
|
|
||||||
\textbf{linux/drivers/mtd/maps/Kconfig}:
|
|
||||||
|
|
||||||
\begin{verbatim}
|
|
||||||
config MTD_DEVICE_FLASH
|
|
||||||
tristate "Device Flash device"
|
|
||||||
depends on ARCHITECTURE && DEVICE
|
|
||||||
help
|
|
||||||
Flash memory access on DEVICE boards. Currently only works with
|
|
||||||
Bootloader Foo and Bootloader Bar.
|
|
||||||
\end{verbatim}
|
|
||||||
|
|
||||||
Then add your source file to the \textbf{linux/drivers/mtd/maps/Makefile}, so
|
|
||||||
that it will be compiled along with the kernel.
|
|
||||||
|
|
||||||
\begin{verbatim}
|
|
||||||
obj-\$(CONFIG_MTD_DEVICE_FLASH) += device-flash.o
|
|
||||||
\end{verbatim}
|
|
||||||
|
|
||||||
You can then write the kernel driver itself, by creating a
|
|
||||||
\textbf{linux/drivers/mtd/maps/device-flash.c} C source file.
|
|
||||||
|
|
||||||
\begin{verbatim}
|
|
||||||
// Includes that are required for the flash map driver to know of the prototypes:
|
|
||||||
#include <asm/io.h>
|
|
||||||
#include <linux/init.h>
|
|
||||||
#include <linux/kernel.h>
|
|
||||||
#include <linux/mtd/map.h>
|
|
||||||
#include <linux/mtd/mtd.h>
|
|
||||||
#include <linux/mtd/partitions.h>
|
|
||||||
#include <linux/vmalloc.h>
|
|
||||||
|
|
||||||
// Put some flash map definitions here:
|
|
||||||
#define WINDOW_ADDR 0x1FC00000 /* Real address of the flash */
|
|
||||||
#define WINDOW_SIZE 0x400000 /* Size of flash */
|
|
||||||
#define BUSWIDTH 2 /* Buswidth */
|
|
||||||
|
|
||||||
static void __exit device_mtd_cleanup(void);
|
|
||||||
|
|
||||||
static struct mtd_info *device_mtd_info;
|
|
||||||
|
|
||||||
static struct map_info devicd_map = {
|
|
||||||
.name = "device",
|
|
||||||
.size = WINDOW_SIZE,
|
|
||||||
.bankwidth = BUSWIDTH,
|
|
||||||
.phys = WINDOW_ADDR,
|
|
||||||
};
|
|
||||||
|
|
||||||
static int __init device_mtd_init(void)
|
|
||||||
{
|
|
||||||
// Display that we found a flash map device
|
|
||||||
printk("device: 0x\%08x at 0x\%08x\n", WINDOW_SIZE, WINDOW_ADDR);
|
|
||||||
// Remap the device address to a kernel address
|
|
||||||
device_map.virt = ioremap(WINDOW_ADDR, WINDOW_SIZE);
|
|
||||||
|
|
||||||
// If impossible to remap, exit with the EIO error
|
|
||||||
if (!device_map.virt) {
|
|
||||||
printk("device: Failed to ioremap\n");
|
|
||||||
return -EIO;
|
|
||||||
}
|
|
||||||
|
|
||||||
// Initialize the device map
|
|
||||||
simple_map_init(&device_map);
|
|
||||||
|
|
||||||
/* MTD informations are closely linked to the flash map device
|
|
||||||
you might also use "jedec_probe" "amd_probe" or "intel_probe" */
|
|
||||||
device_mtd_info = do_map_probe("cfi_probe", &device_map);
|
|
||||||
|
|
||||||
if (device_mtd_info) {
|
|
||||||
device_mtd_info->owner = THIS_MODULE;
|
|
||||||
|
|
||||||
int parsed_nr_parts = 0;
|
|
||||||
|
|
||||||
// We try here to use the partition schema provided by the bootloader specific code
|
|
||||||
if (parsed_nr_parts == 0) {
|
|
||||||
int ret = parse_bootloader_partitions(device_mtd_info, &parsed_parts, 0);
|
|
||||||
if (ret > 0) {
|
|
||||||
part_type = "BootLoader";
|
|
||||||
parsed_nr_parts = ret;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
add_mtd_partitions(devicd_mtd_info, parsed_parts, parsed_nr_parts);
|
|
||||||
|
|
||||||
return 0;
|
|
||||||
}
|
|
||||||
iounmap(device_map.virt);
|
|
||||||
|
|
||||||
return -ENXIO;
|
|
||||||
}
|
|
||||||
|
|
||||||
// This function will make the driver clean up the MTD device mapping
|
|
||||||
static void __exit device_mtd_cleanup(void)
|
|
||||||
{
|
|
||||||
// If we found a MTD device before
|
|
||||||
if (device_mtd_info) {
|
|
||||||
// Delete every partitions
|
|
||||||
del_mtd_partitions(device_mtd_info);
|
|
||||||
// Delete the associated map
|
|
||||||
map_destroy(device_mtd_info);
|
|
||||||
}
|
|
||||||
|
|
||||||
// If the virtual address is already in use
|
|
||||||
if (device_map.virt) {
|
|
||||||
// Unmap the physical address to a kernel space address
|
|
||||||
iounmap(device_map.virt);
|
|
||||||
// Reset the structure field
|
|
||||||
device_map.virt = 0;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
// Macros that indicate which function is called on loading/unloading the module
|
|
||||||
module_init(device_mtd_init);
|
|
||||||
module_exit(device_mtd_cleanup);
|
|
||||||
|
|
||||||
|
|
||||||
// Macros defining license and author, parameters can be defined here too.
|
|
||||||
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 -9n -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}
|
|
||||||
|
|
@ -1,52 +0,0 @@
|
||||||
OpenWrt as an open source software opens its development to the community by
|
|
||||||
having a publicly browseable subversion repository. The Trac software which
|
|
||||||
comes along with a Subversion frontend, a Wiki and a ticket reporting system
|
|
||||||
is used as an interface between developers, users and contributors in order to
|
|
||||||
make the whole development process much easier and efficient.
|
|
||||||
|
|
||||||
We make distinction between two kinds of people within the Trac system:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item developers, able to report, close and fix tickets
|
|
||||||
\item reporters, able to add a comment, patch, or request ticket status
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\subsubsection{Opening a ticket}
|
|
||||||
|
|
||||||
A reporter might want to open a ticket for the following reasons:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item a bug affects a specific hardware and/or software and needs to be fixed
|
|
||||||
\item a specific software package would be seen as part of the official OpenWrt repository
|
|
||||||
\item a feature should be added or removed from OpenWrt
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
Regarding the kind of ticket that is open, a patch is welcome in those cases:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item new package to be included in OpenWrt
|
|
||||||
\item fix for a bug that works for the reporter and has no known side effect
|
|
||||||
\item new features that can be added by modifying existing OpenWrt files
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
Once the ticket is open, a developer will take care of it, if so, the ticket is marked
|
|
||||||
as "accepted" with the developer name. You can add comments at any time to the ticket,
|
|
||||||
even when it is closed.
|
|
||||||
|
|
||||||
\subsubsection{Closing a ticket}
|
|
||||||
|
|
||||||
A ticket might be closed by a developer because:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item the problem is already fixed (wontfix)
|
|
||||||
\item the problem described is not judged as valid, and comes along with an explanation why (invalid)
|
|
||||||
\item the developers know that this bug will be fixed upstream (wontfix)
|
|
||||||
\item the problem is very similar to something that has already been reported (duplicate)
|
|
||||||
\item the problem cannot be reproduced by the developers (worksforme)
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
At the same time, the reporter may want to get the ticket closed since he is not
|
|
||||||
longer able to trigger the bug, or found it invalid by himself.
|
|
||||||
|
|
||||||
When a ticket is closed by a developer and marked as "fixed", the comment contains
|
|
||||||
the subversion changeset which corrects the bug.
|
|
||||||
594
docs/build.tex
594
docs/build.tex
|
|
@ -1,594 +0,0 @@
|
||||||
One of the biggest challenges to getting started with embedded devices is that you
|
|
||||||
cannot just install a copy of Linux and expect to be able to compile a firmware.
|
|
||||||
Even if you did remember to install a compiler and every development tool offered,
|
|
||||||
you still would not have the basic set of tools needed to produce a firmware image.
|
|
||||||
The embedded device represents an entirely new hardware platform, which is
|
|
||||||
most of the time incompatible with the hardware on your development machine, so in a process called
|
|
||||||
cross compiling you need to produce a new compiler capable of generating code for
|
|
||||||
your embedded platform, and then use it to compile a basic Linux distribution to
|
|
||||||
run on your device.
|
|
||||||
|
|
||||||
The process of creating a cross compiler can be tricky, it is not something that is
|
|
||||||
regularly attempted and so there is a certain amount of mystery and black magic
|
|
||||||
associated with it. In many cases when you are dealing with embedded devices you will
|
|
||||||
be provided with a binary copy of a compiler and basic libraries rather than
|
|
||||||
instructions for creating your own -- it is a time saving step but at the same time
|
|
||||||
often means you will be using a rather dated set of tools. Likewise, it is also common
|
|
||||||
to be provided with a patched copy of the Linux kernel from the board or chip vendor,
|
|
||||||
but this is also dated and it can be difficult to spot exactly what has been
|
|
||||||
modified to make the kernel run on the embedded platform.
|
|
||||||
|
|
||||||
\subsection{Building an image}
|
|
||||||
|
|
||||||
OpenWrt takes a different approach to building a firmware; downloading, patching
|
|
||||||
and compiling everything from scratch, including the cross compiler. To put it
|
|
||||||
in simpler terms, OpenWrt does not contain any executables or even sources, it is an
|
|
||||||
automated system for downloading the sources, patching them to work with the given
|
|
||||||
platform and compiling them correctly for that platform. What this means is that
|
|
||||||
just by changing the template, you can change any step in the process.
|
|
||||||
|
|
||||||
As an example, if a new kernel is released, a simple change to one of the Makefiles
|
|
||||||
will download the latest kernel, patch it to run on the embedded platform and produce
|
|
||||||
a new firmware image -- there is no work to be done trying to track down an unmodified
|
|
||||||
copy of the existing kernel to see what changes had been made, the patches are
|
|
||||||
already provided and the process ends up almost completely transparent. This does not
|
|
||||||
just apply to the kernel, but to anything included with OpenWrt -- It is this one
|
|
||||||
simple understated concept which is what allows OpenWrt to stay on the bleeding edge
|
|
||||||
with the latest compilers, latest kernels and latest applications.
|
|
||||||
|
|
||||||
So let's take a look at OpenWrt and see how this all works.
|
|
||||||
|
|
||||||
|
|
||||||
\subsubsection{Download OpenWrt}
|
|
||||||
|
|
||||||
OpenWrt can be downloaded via subversion using the following command:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
$ svn checkout svn://svn.openwrt.org/openwrt/trunk openwrt-trunk
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
Additionally, there is a trac interface on \href{https://dev.openwrt.org/}{https://dev.openwrt.org/}
|
|
||||||
which can be used to monitor svn commits and browse the source repository.
|
|
||||||
|
|
||||||
|
|
||||||
\subsubsection{The directory structure}
|
|
||||||
|
|
||||||
There are four key directories in the base:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{tools}
|
|
||||||
\item \texttt{toolchain}
|
|
||||||
\item \texttt{package}
|
|
||||||
\item \texttt{target}
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\texttt{tools} and \texttt{toolchain} refer to common tools which will be
|
|
||||||
used to build the firmware image, the compiler, and the C library.
|
|
||||||
The result of this is three new directories, \texttt{build\_dir/host}, which is a temporary
|
|
||||||
directory for building the target independent tools, \texttt{build\_dir/toolchain-\textit{<arch>}*}
|
|
||||||
which is used for building the toolchain for a specific architecture, and
|
|
||||||
\texttt{staging\_dir/toolchain-\textit{<arch>}*} where the resulting toolchain is installed.
|
|
||||||
You will not need to do anything with the toolchain directory unless you intend to
|
|
||||||
add a new version of one of the components above.
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{build\_dir/host}
|
|
||||||
\item \texttt{build\_dir/toolchain-\textit{<arch>}*}
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\texttt{package} is for exactly that -- packages. In an OpenWrt firmware, almost everything
|
|
||||||
is an \texttt{.ipk}, a software package which can be added to the firmware to provide new
|
|
||||||
features or removed to save space. Note that packages are also maintained outside of the main
|
|
||||||
trunk and can be obtained from subversion using the package feeds system:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
$ ./scripts/feeds update
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
Those packages can be used to extend the functionality of the build system and need to be
|
|
||||||
symlinked into the main trunk. Once you do that, the packages will show up in the menu for
|
|
||||||
configuration. You would do something like this:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
$ ./scripts/feeds search nmap
|
|
||||||
Search results in feed 'packages':
|
|
||||||
nmap Network exploration and/or security auditing utility
|
|
||||||
|
|
||||||
$ ./scripts/feeds install nmap
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
To include all packages, issue the following command:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
$ make package/symlinks
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\texttt{target} refers to the embedded platform, this contains items which are specific to
|
|
||||||
a specific embedded platform. Of particular interest here is the "\texttt{target/linux}"
|
|
||||||
directory which is broken down by platform \textit{<arch>} and contains the patches to the
|
|
||||||
kernel, profile config, for a particular platform. There's also the "\texttt{target/image}" directory
|
|
||||||
which describes how to package a firmware for a specific platform.
|
|
||||||
|
|
||||||
Both the target and package steps will use the directory "\texttt{build\_dir/\textit{<arch>}}"
|
|
||||||
as a temporary directory for compiling. Additionally, anything downloaded by the toolchain,
|
|
||||||
target or package steps will be placed in the "\texttt{dl}" directory.
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{build\_dir/\textit{<arch>}}
|
|
||||||
\item \texttt{dl}
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\subsubsection{Building OpenWrt}
|
|
||||||
|
|
||||||
While the OpenWrt build environment was intended mostly for developers, it also has to be
|
|
||||||
simple enough that an inexperienced end user can easily build his or her own customized firmware.
|
|
||||||
|
|
||||||
Running the command "\texttt{make menuconfig}" will bring up OpenWrt's configuration menu
|
|
||||||
screen, through this menu you can select which platform you're targeting, which versions of
|
|
||||||
the toolchain you want to use to build and what packages you want to install into the
|
|
||||||
firmware image. Note that it will also check to make sure you have the basic dependencies for it
|
|
||||||
to run correctly. If that fails, you will need to install some more tools in your local environment
|
|
||||||
before you can begin.
|
|
||||||
|
|
||||||
Similar to the linux kernel config, almost every option has three choices,
|
|
||||||
\texttt{y/m/n} which are represented as follows:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item{\texttt{<*>} (pressing y)} \\
|
|
||||||
This will be included in the firmware image
|
|
||||||
\item{\texttt{<M>} (pressing m)} \\
|
|
||||||
This will be compiled but not included (for later install)
|
|
||||||
\item{\texttt{< >} (pressing n)} \\
|
|
||||||
This will not be compiled
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
After you've finished with the menu configuration, exit and when prompted, save your
|
|
||||||
configuration changes.
|
|
||||||
|
|
||||||
If you want, you can also modify the kernel config for the selected target system.
|
|
||||||
simply run "\texttt{make kernel\_menuconfig}" and the build system will unpack the kernel sources
|
|
||||||
(if necessary), run menuconfig inside of the kernel tree, and then copy the kernel config
|
|
||||||
to \texttt{target/linux/\textit{<platform>}/config} so that it is preserved over
|
|
||||||
"\texttt{make clean}" calls.
|
|
||||||
|
|
||||||
To begin compiling the firmware, type "\texttt{make}". By default
|
|
||||||
OpenWrt will only display a high level overview of the compile process and not each individual
|
|
||||||
command.
|
|
||||||
|
|
||||||
\subsubsection{Example:}
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
make[2] toolchain/install
|
|
||||||
make[3] -C toolchain install
|
|
||||||
make[2] target/compile
|
|
||||||
make[3] -C target compile
|
|
||||||
make[4] -C target/utils prepare
|
|
||||||
|
|
||||||
[...]
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
This makes it easier to monitor which step it's actually compiling and reduces the amount
|
|
||||||
of noise caused by the compile output. To see the full output, run the command
|
|
||||||
"\texttt{make V=99}".
|
|
||||||
|
|
||||||
During the build process, buildroot will download all sources to the "\texttt{dl}"
|
|
||||||
directory and will start patching and compiling them in the "\texttt{build\_dir/\textit{<arch>}}"
|
|
||||||
directory. When finished, the resulting firmware will be in the "\texttt{bin}" directory
|
|
||||||
and packages will be in the "\texttt{bin/packages}" directory.
|
|
||||||
|
|
||||||
|
|
||||||
\subsection{Creating packages}
|
|
||||||
|
|
||||||
One of the things that we've attempted to do with OpenWrt's template system is make it
|
|
||||||
incredibly easy to port software to OpenWrt. If you look at a typical package directory
|
|
||||||
in OpenWrt you'll find several things:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{package/\textit{<name>}/Makefile}
|
|
||||||
\item \texttt{package/\textit{<name>}/patches}
|
|
||||||
\item \texttt{package/\textit{<name>}/files}
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
The patches directory is optional and typically contains bug fixes or optimizations to
|
|
||||||
reduce the size of the executable. The package makefile is the important item, provides
|
|
||||||
the steps actually needed to download and compile the package.
|
|
||||||
|
|
||||||
The files directory is also optional and typicall contains package specific startup scripts or default configuration files that can be used out of the box with OpenWrt.
|
|
||||||
|
|
||||||
Looking at one of the package makefiles, you'd hardly recognize it as a makefile.
|
|
||||||
Through what can only be described as blatant disregard and abuse of the traditional
|
|
||||||
make format, the makefile has been transformed into an object oriented template which
|
|
||||||
simplifies the entire ordeal.
|
|
||||||
|
|
||||||
Here for example, is \texttt{package/bridge/Makefile}:
|
|
||||||
|
|
||||||
\begin{Verbatim}[frame=single,numbers=left]
|
|
||||||
|
|
||||||
include $(TOPDIR)/rules.mk
|
|
||||||
|
|
||||||
PKG_NAME:=bridge
|
|
||||||
PKG_VERSION:=1.0.6
|
|
||||||
PKG_RELEASE:=1
|
|
||||||
|
|
||||||
PKG_SOURCE:=bridge-utils-$(PKG_VERSION).tar.gz
|
|
||||||
PKG_SOURCE_URL:=@SF/bridge
|
|
||||||
PKG_MD5SUM:=9b7dc52656f5cbec846a7ba3299f73bd
|
|
||||||
PKG_CAT:=zcat
|
|
||||||
|
|
||||||
PKG_BUILD_DIR:=$(BUILD_DIR)/bridge-utils-$(PKG_VERSION)
|
|
||||||
|
|
||||||
include $(INCLUDE_DIR)/package.mk
|
|
||||||
|
|
||||||
define Package/bridge
|
|
||||||
SECTION:=net
|
|
||||||
CATEGORY:=Base system
|
|
||||||
TITLE:=Ethernet bridging configuration utility
|
|
||||||
URL:=http://bridge.sourceforge.net/
|
|
||||||
endef
|
|
||||||
|
|
||||||
define Package/bridge/description
|
|
||||||
Manage ethernet bridging:
|
|
||||||
a way to connect networks together to form a larger network.
|
|
||||||
endef
|
|
||||||
|
|
||||||
define Build/Configure
|
|
||||||
$(call Build/Configure/Default, \
|
|
||||||
--with-linux-headers="$(LINUX_DIR)" \
|
|
||||||
)
|
|
||||||
endef
|
|
||||||
|
|
||||||
define Package/bridge/install
|
|
||||||
$(INSTALL_DIR) $(1)/usr/sbin
|
|
||||||
$(INSTALL_BIN) $(PKG_BUILD_DIR)/brctl/brctl $(1)/usr/sbin/
|
|
||||||
endef
|
|
||||||
|
|
||||||
$(eval $(call BuildPackage,bridge))
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
As you can see, there's not much work to be done; everything is hidden in other makefiles
|
|
||||||
and abstracted to the point where you only need to specify a few variables.
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{PKG\_NAME} \\
|
|
||||||
The name of the package, as seen via menuconfig and ipkg
|
|
||||||
\item \texttt{PKG\_VERSION} \\
|
|
||||||
The upstream version number that we are downloading
|
|
||||||
\item \texttt{PKG\_RELEASE} \\
|
|
||||||
The version of this package Makefile
|
|
||||||
\item \texttt{PKG\_SOURCE} \\
|
|
||||||
The filename of the original sources
|
|
||||||
\item \texttt{PKG\_SOURCE\_URL} \\
|
|
||||||
Where to download the sources from (no trailing slash), you can add multiple download sources by separating them with a \\ and a carriage return.
|
|
||||||
\item \texttt{PKG\_MD5SUM} \\
|
|
||||||
A checksum to validate the download
|
|
||||||
\item \texttt{PKG\_CAT} \\
|
|
||||||
How to decompress the sources (zcat, bzcat, unzip)
|
|
||||||
\item \texttt{PKG\_BUILD\_DIR} \\
|
|
||||||
Where to compile the package
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
The \texttt{PKG\_*} variables define where to download the package from;
|
|
||||||
\texttt{@SF} is a special keyword for downloading packages from sourceforge. There is also
|
|
||||||
another keyword of \texttt{@GNU} for grabbing GNU source releases. If any of the above mentionned download source fails, the OpenWrt mirrors will be used as source.
|
|
||||||
|
|
||||||
The md5sum (if present) is used to verify the package was downloaded correctly and
|
|
||||||
\texttt{PKG\_BUILD\_DIR} defines where to find the package after the sources are
|
|
||||||
uncompressed into \texttt{\$(BUILD\_DIR)}.
|
|
||||||
|
|
||||||
At the bottom of the file is where the real magic happens, "BuildPackage" is a macro
|
|
||||||
set up by the earlier include statements. BuildPackage only takes one argument directly --
|
|
||||||
the name of the package to be built, in this case "\texttt{bridge}". All other information
|
|
||||||
is taken from the define blocks. This is a way of providing a level of verbosity, it's
|
|
||||||
inherently clear what the contents of the \texttt{description} template in
|
|
||||||
\texttt{Package/bridge} is, which wouldn't be the case if we passed this information
|
|
||||||
directly as the Nth argument to \texttt{BuildPackage}.
|
|
||||||
|
|
||||||
\texttt{BuildPackage} uses the following defines:
|
|
||||||
|
|
||||||
\textbf{\texttt{Package/\textit{<name>}}:} \\
|
|
||||||
\texttt{\textit{<name>}} matches the argument passed to buildroot, this describes
|
|
||||||
the package the menuconfig and ipkg entries. Within \texttt{Package/\textit{<name>}}
|
|
||||||
you can define the following variables:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{SECTION} \\
|
|
||||||
The section of package (currently unused)
|
|
||||||
\item \texttt{CATEGORY} \\
|
|
||||||
Which menu it appears in menuconfig: Network, Sound, Utilities, Multimedia ...
|
|
||||||
\item \texttt{TITLE} \\
|
|
||||||
A short description of the package
|
|
||||||
\item \texttt{URL} \\
|
|
||||||
Where to find the original software
|
|
||||||
\item \texttt{MAINTAINER} (optional) \\
|
|
||||||
Who to contact concerning the package
|
|
||||||
\item \texttt{DEPENDS} (optional) \\
|
|
||||||
Which packages must be built/installed before this package. To reference a dependency defined in the
|
|
||||||
same Makefile, use \textit{<dependency name>}. If defined as an external package, use
|
|
||||||
\textit{+<dependency name>}. For a kernel version dependency use: \textit{@LINUX\_2\_<minor version>}
|
|
||||||
\item \texttt{BUILDONLY} (optional) \\
|
|
||||||
Set this option to 1 if you do NOT want your package to appear in menuconfig.
|
|
||||||
This is useful for packages which are only used as build dependencies.
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\textbf{\texttt{Package/\textit{<name>}/conffiles} (optional):} \\
|
|
||||||
A list of config files installed by this package, one file per line.
|
|
||||||
|
|
||||||
\textbf{\texttt{Build/Prepare} (optional):} \\
|
|
||||||
A set of commands to unpack and patch the sources. You may safely leave this
|
|
||||||
undefined.
|
|
||||||
|
|
||||||
\textbf{\texttt{Build/Configure} (optional):} \\
|
|
||||||
You can leave this undefined if the source doesn't use configure or has a
|
|
||||||
normal config script, otherwise you can put your own commands here or use
|
|
||||||
"\texttt{\$(call Build/Configure/Default,\textit{<first list of arguments, second list>})}" as above to
|
|
||||||
pass in additional arguments for a standard configure script. The first list of arguments will be passed
|
|
||||||
to the configure script like that: \texttt{--arg 1} \texttt{--arg 2}. The second list contains arguments that should be
|
|
||||||
defined before running the configure script such as autoconf or compiler specific variables.
|
|
||||||
|
|
||||||
To make it easier to modify the configure command line, you can either extend or completely override the following variables:
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{CONFIGURE\_ARGS} \\
|
|
||||||
Contains all command line arguments (format: \texttt{--arg 1} \texttt{--arg 2})
|
|
||||||
\item \texttt{CONFIGURE\_VARS} \\
|
|
||||||
Contains all environment variables that are passed to ./configure (format: \texttt{NAME="value"})
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\textbf{\texttt{Build/Compile} (optional):} \\
|
|
||||||
How to compile the source; in most cases you should leave this undefined.
|
|
||||||
|
|
||||||
As with \texttt{Build/Configure} there are two variables that allow you to override
|
|
||||||
the make command line environment variables and flags:
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{MAKE\_FLAGS} \\
|
|
||||||
Contains all command line arguments (typically variable overrides like \texttt{NAME="value"}
|
|
||||||
\item \texttt{MAKE\_VARS} \\
|
|
||||||
Contains all environment variables that are passed to the make command
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\textbf{\texttt{Build/InstallDev} (optional):} \\
|
|
||||||
If your package provides a library that needs to be made available to other packages,
|
|
||||||
you can use the \texttt{Build/InstallDev} template to copy it into the staging directory
|
|
||||||
which is used to collect all files that other packages might depend on at build time.
|
|
||||||
When it is called by the build system, two parameters are passed to it. \texttt{\$(1)} points to
|
|
||||||
the regular staging dir, typically \texttt{staging\_dir/\textit{ARCH}}, while \texttt{\$(2)} points
|
|
||||||
to \texttt{staging\_dir/host}. The host staging dir is only used for binaries, which are
|
|
||||||
to be executed or linked against on the host and its \texttt{bin/} subdirectory is included
|
|
||||||
in the \texttt{PATH} which is passed down to the build system processes.
|
|
||||||
Please use \texttt{\$(1)} and \texttt{\$(2)} here instead of the build system variables
|
|
||||||
\texttt{\$(STAGING\_DIR)} and \texttt{\$(STAGING\_DIR\_HOST)}, because the build system behavior
|
|
||||||
when staging libraries might change in the future to include automatic uninstallation.
|
|
||||||
|
|
||||||
\textbf{\texttt{Package/\textit{<name>}/install}:} \\
|
|
||||||
A set of commands to copy files out of the compiled source and into the ipkg
|
|
||||||
which is represented by the \texttt{\$(1)} directory. Note that there are currently
|
|
||||||
4 defined install macros:
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{INSTALL\_DIR} \\
|
|
||||||
install -d -m0755
|
|
||||||
\item \texttt{INSTALL\_BIN} \\
|
|
||||||
install -m0755
|
|
||||||
\item \texttt{INSTALL\_DATA} \\
|
|
||||||
install -m0644
|
|
||||||
\item \texttt{INSTALL\_CONF} \\
|
|
||||||
install -m0600
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
The reason that some of the defines are prefixed by "\texttt{Package/\textit{<name>}}"
|
|
||||||
and others are simply "\texttt{Build}" is because of the possibility of generating
|
|
||||||
multiple packages from a single source. OpenWrt works under the assumption of one
|
|
||||||
source per package Makefile, but you can split that source into as many packages as
|
|
||||||
desired. Since you only need to compile the sources once, there's one global set of
|
|
||||||
"\texttt{Build}" defines, but you can add as many "Package/<name>" defines as you want
|
|
||||||
by adding extra calls to \texttt{BuildPackage} -- see the dropbear package for an example.
|
|
||||||
|
|
||||||
After you have created your \texttt{package/\textit{<name>}/Makefile}, the new package
|
|
||||||
will automatically show in the menu the next time you run "make menuconfig" and if selected
|
|
||||||
will be built automatically the next time "\texttt{make}" is run.
|
|
||||||
|
|
||||||
\subsection{Creating binary packages}
|
|
||||||
|
|
||||||
You might want to create binary packages and include them in the resulting images as packages.
|
|
||||||
To do so, you can use the following template, which basically sets to nothing the Configure and
|
|
||||||
Compile templates.
|
|
||||||
|
|
||||||
\begin{Verbatim}[frame=single,numbers=left]
|
|
||||||
|
|
||||||
include $(TOPDIR)/rules.mk
|
|
||||||
|
|
||||||
PKG_NAME:=binpkg
|
|
||||||
PKG_VERSION:=1.0
|
|
||||||
PKG_RELEASE:=1
|
|
||||||
|
|
||||||
PKG_SOURCE:=binpkg-$(PKG_VERSION).tar.gz
|
|
||||||
PKG_SOURCE_URL:=http://server
|
|
||||||
PKG_MD5SUM:=9b7dc52656f5cbec846a7ba3299f73bd
|
|
||||||
PKG_CAT:=zcat
|
|
||||||
|
|
||||||
include $(INCLUDE_DIR)/package.mk
|
|
||||||
|
|
||||||
define Package/binpkg
|
|
||||||
SECTION:=net
|
|
||||||
CATEGORY:=Network
|
|
||||||
TITLE:=Binary package
|
|
||||||
endef
|
|
||||||
|
|
||||||
define Package/bridge/description
|
|
||||||
Binary package
|
|
||||||
endef
|
|
||||||
|
|
||||||
define Build/Configure
|
|
||||||
endef
|
|
||||||
|
|
||||||
define Build/Compile
|
|
||||||
endef
|
|
||||||
|
|
||||||
define Package/bridge/install
|
|
||||||
$(INSTALL_DIR) $(1)/usr/sbin
|
|
||||||
$(INSTALL_BIN) $(PKG_BUILD_DIR)/* $(1)/usr/sbin/
|
|
||||||
endef
|
|
||||||
|
|
||||||
$(eval $(call BuildPackage,bridge))
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
Provided that the tarball which contains the binaries reflects the final
|
|
||||||
directory layout (/usr, /lib ...), it becomes very easy to get your package
|
|
||||||
look like one build from sources.
|
|
||||||
|
|
||||||
Note that using the same technique, you can easily create binary pcakages
|
|
||||||
for your proprietary kernel modules as well.
|
|
||||||
|
|
||||||
\subsection{Creating kernel modules packages}
|
|
||||||
|
|
||||||
The OpenWrt distribution makes the distinction between two kind of kernel modules, those coming along with the mainline kernel, and the others available as a separate project. We will see later that a common template is used for both of them.
|
|
||||||
|
|
||||||
For kernel modules that are part of the mainline kernel source, the makefiles are located in \textit{package/kernel/modules/*.mk} and they appear under the section "Kernel modules"
|
|
||||||
|
|
||||||
For external kernel modules, you can add them to the build system just like if they were software packages by defining a KernelPackage section in the package makefile.
|
|
||||||
|
|
||||||
Here for instance the Makefile for the I2C subsytem kernel modules :
|
|
||||||
|
|
||||||
\begin{Verbatim}[frame=single,numbers=left]
|
|
||||||
|
|
||||||
I2CMENU:=I2C Bus
|
|
||||||
|
|
||||||
define KernelPackage/i2c-core
|
|
||||||
TITLE:=I2C support
|
|
||||||
DESCRIPTION:=Kernel modules for i2c support
|
|
||||||
SUBMENU:=$(I2CMENU)
|
|
||||||
KCONFIG:=CONFIG_I2C_CORE CONFIG_I2C_DEV
|
|
||||||
FILES:=$(MODULES_DIR)/kernel/drivers/i2c/*.$(LINUX_KMOD_SUFFIX)
|
|
||||||
AUTOLOAD:=$(call AutoLoad,50,i2c-core i2c-dev)
|
|
||||||
endef
|
|
||||||
$(eval $(call KernelPackage,i2c-core))
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
To group kernel modules under a common description in menuconfig, you might want to define a \textit{<description>MENU} variable on top of the kernel modules makefile.
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{TITLE} \\
|
|
||||||
The name of the module as seen via menuconfig
|
|
||||||
\item \texttt{DESCRIPTION} \\
|
|
||||||
The description as seen via help in menuconfig
|
|
||||||
\item \texttt{SUBMENU} \\
|
|
||||||
The sub menu under which this package will be seen
|
|
||||||
\item \texttt{KCONFIG} \\
|
|
||||||
Kernel configuration option dependency. For external modules, remove it.
|
|
||||||
\item \texttt{FILES} \\
|
|
||||||
Files you want to inlude to this kernel module package, separate with spaces.
|
|
||||||
\item \texttt{AUTOLOAD} \\
|
|
||||||
Modules that will be loaded automatically on boot, the order you write them is the order they would be loaded.
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
After you have created your \texttt{package/kernel/modules/\textit{<name>}.mk}, the new kernel modules package
|
|
||||||
will automatically show in the menu under "Kernel modules" next time you run "make menuconfig" and if selected
|
|
||||||
will be built automatically the next time "\texttt{make}" is run.
|
|
||||||
|
|
||||||
\subsection{Conventions}
|
|
||||||
|
|
||||||
There are a couple conventions to follow regarding packages:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{files}
|
|
||||||
\begin{enumerate}
|
|
||||||
\item configuration files follow the convention \\
|
|
||||||
\texttt{\textit{<name>}.conf}
|
|
||||||
\item init files follow the convention \\
|
|
||||||
\texttt{\textit{<name>}.init}
|
|
||||||
\end{enumerate}
|
|
||||||
\item \texttt{patches}
|
|
||||||
\begin{enumerate}
|
|
||||||
\item patches are numerically prefixed and named related to what they do
|
|
||||||
\end{enumerate}
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\subsection{Troubleshooting}
|
|
||||||
|
|
||||||
If you find your package doesn't show up in menuconfig, try the following command to
|
|
||||||
see if you get the correct description:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
TOPDIR=$PWD make -C package/<name> DUMP=1 V=99
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
If you're just having trouble getting your package to compile, there's a few
|
|
||||||
shortcuts you can take. Instead of waiting for make to get to your package, you can
|
|
||||||
run one of the following:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{make package/\textit{<name>}/clean V=99}
|
|
||||||
\item \texttt{make package/\textit{<name>}/install V=99}
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
Another nice trick is that if the source directory under \texttt{build\_dir/\textit{<arch>}}
|
|
||||||
is newer than the package directory, it won't clobber it by unpacking the sources again.
|
|
||||||
If you were working on a patch you could simply edit the sources under the
|
|
||||||
\texttt{build\_dir/\textit{<arch>}/\textit{<source>}} directory and run the install command above,
|
|
||||||
when satisfied, copy the patched sources elsewhere and diff them with the unpatched
|
|
||||||
sources. A warning though - if you go modify anything under \texttt{package/\textit{<name>}}
|
|
||||||
it will remove the old sources and unpack a fresh copy.
|
|
||||||
|
|
||||||
Other useful targets include:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{make package/\textit{<name>}/prepare V=99}
|
|
||||||
\item \texttt{make package/\textit{<name>}/compile V=99}
|
|
||||||
\item \texttt{make package/\textit{<name>}/configure V=99}
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
|
|
||||||
\subsection{Using build environments}
|
|
||||||
OpenWrt provides a means of building images for multiple configurations
|
|
||||||
which can use multiple targets in one single checkout. These \emph{environments}
|
|
||||||
store a copy of the .config file generated by \texttt{make menuconfig} and the contents
|
|
||||||
of the \texttt{./files} folder.
|
|
||||||
The script \texttt{./scripts/env} is used to manage these environments, it uses
|
|
||||||
\texttt{git} (which needs to be installed on your system) as backend for version control.
|
|
||||||
|
|
||||||
The command
|
|
||||||
\begin{Verbatim}
|
|
||||||
./scripts/env help
|
|
||||||
\end{Verbatim}
|
|
||||||
produces a short help text with a list of commands.
|
|
||||||
|
|
||||||
To create a new environment named \texttt{current}, run the following command
|
|
||||||
\begin{Verbatim}
|
|
||||||
./scripts/env new current
|
|
||||||
\end{Verbatim}
|
|
||||||
This will move your \texttt{.config} file and \texttt{./files} (if it exists) to
|
|
||||||
the \texttt{env/} subdirectory and create symlinks in the base folder.
|
|
||||||
|
|
||||||
After running make menuconfig or changing things in files/, your current state will
|
|
||||||
differ from what has been saved before. To show these changes, use:
|
|
||||||
\begin{Verbatim}
|
|
||||||
./scripts/env diff
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
If you want to save these changes, run:
|
|
||||||
\begin{Verbatim}
|
|
||||||
./scripts/env save
|
|
||||||
\end{Verbatim}
|
|
||||||
If you want to revert your changes to the previously saved copy, run:
|
|
||||||
\begin{Verbatim}
|
|
||||||
./scripts/env revert
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
If you want, you can now create a second environment using the \texttt{new} command.
|
|
||||||
It will ask you whether you want to make it a clone of the current environment (e.g.
|
|
||||||
for minor changes) or if you want to start with a clean version (e.g. for selecting
|
|
||||||
a new target).
|
|
||||||
|
|
||||||
To switch to a different environment (e.g. \texttt{test1}), use:
|
|
||||||
\begin{Verbatim}
|
|
||||||
./scripts/env switch test1
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
To rename the current branch to a new name (e.g. \texttt{test2}), use:
|
|
||||||
\begin{Verbatim}
|
|
||||||
./scripts/env rename test2
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
If you want to get rid of environment switching and keep everything in the base directory
|
|
||||||
again, use:
|
|
||||||
\begin{Verbatim}
|
|
||||||
./scripts/env clear
|
|
||||||
\end{Verbatim}
|
|
||||||
101
docs/config.tex
101
docs/config.tex
|
|
@ -1,101 +0,0 @@
|
||||||
\subsubsection{Structure of the configuration files}
|
|
||||||
|
|
||||||
The config files are divided into sections and options/values.
|
|
||||||
|
|
||||||
Every section has a type, but does not necessarily have a name.
|
|
||||||
Every option has a name and a value and is assigned to the section
|
|
||||||
it was written under.
|
|
||||||
|
|
||||||
Syntax:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config <type> ["<name>"] # Section
|
|
||||||
option <name> "<value>" # Option
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
Every parameter needs to be a single string and is formatted exactly
|
|
||||||
like a parameter for a shell function. The same rules for Quoting and
|
|
||||||
special characters also apply, as it is parsed by the shell.
|
|
||||||
|
|
||||||
\subsubsection{Parsing configuration files in custom scripts}
|
|
||||||
|
|
||||||
To be able to load configuration files, you need to include the common
|
|
||||||
functions with:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
. /lib/functions.sh
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
Then you can use \texttt{config\_load \textit{<name>}} to load config files. The function
|
|
||||||
first checks for \textit{<name>} as absolute filename and falls back to loading
|
|
||||||
it from \texttt{/etc/config} (which is the most common way of using it).
|
|
||||||
|
|
||||||
If you want to use special callbacks for sections and/or options, you
|
|
||||||
need to define the following shell functions before running \texttt{config\_load}
|
|
||||||
(after including \texttt{/lib/functions.sh}):
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config_cb() {
|
|
||||||
local type="$1"
|
|
||||||
local name="$2"
|
|
||||||
# commands to be run for every section
|
|
||||||
}
|
|
||||||
|
|
||||||
option_cb() {
|
|
||||||
# commands to be run for every option
|
|
||||||
}
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
You can also alter \texttt{option\_cb} from \texttt{config\_cb} based on the section type.
|
|
||||||
This allows you to process every single config section based on its type
|
|
||||||
individually.
|
|
||||||
|
|
||||||
\texttt{config\_cb} is run every time a new section starts (before options are being
|
|
||||||
processed). You can access the last section through the \texttt{CONFIG\_SECTION}
|
|
||||||
variable. Also an extra call to \texttt{config\_cb} (without a new section) is generated
|
|
||||||
after \texttt{config\_load} is done.
|
|
||||||
That allows you to process sections both before and after all options were
|
|
||||||
processed.
|
|
||||||
|
|
||||||
Another way of iterating on config sections is using the \texttt{config\_foreach} command.
|
|
||||||
|
|
||||||
Syntax:
|
|
||||||
\begin{Verbatim}
|
|
||||||
config_foreach <function name> [<sectiontype>] [<arguments...>]
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
This command will run the supplied function for every single config section in the currently
|
|
||||||
loaded config. The section name will be passed to the function as argument 1.
|
|
||||||
If the section type is added to the command line, the function will only be called for
|
|
||||||
sections of the given type.
|
|
||||||
|
|
||||||
|
|
||||||
You can access already processed options with the \texttt{config\_get} command
|
|
||||||
Syntax:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
# print the value of the option
|
|
||||||
config_get <section> <option>
|
|
||||||
|
|
||||||
# store the value inside the variable
|
|
||||||
config_get <variable> <section> <option>
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
In busybox ash the three-option \texttt{config\_get} is faster, because it does not
|
|
||||||
result in an extra fork, so it is the preferred way.
|
|
||||||
|
|
||||||
Additionally you can also modify or add options to sections by using the
|
|
||||||
\texttt{config\_set} command.
|
|
||||||
|
|
||||||
Syntax:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config_set <section> <option> <value>
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
If a config section is unnamed, an automatically generated name will
|
|
||||||
be assigned internally, e.g. \texttt{cfg1}, \texttt{cfg2}, ...
|
|
||||||
|
|
||||||
While it is possible, using unnamed sections through these autogenerated names is
|
|
||||||
strongly discouraged. Use callbacks or \texttt{config\_foreach} instead.
|
|
||||||
|
|
||||||
|
|
@ -1,61 +0,0 @@
|
||||||
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.
|
|
||||||
|
|
@ -1,60 +0,0 @@
|
||||||
Because OpenWrt uses its own init script system, all init scripts must be installed
|
|
||||||
as \texttt{/etc/init.d/\textit{name}} use \texttt{/etc/rc.common} as a wrapper.
|
|
||||||
|
|
||||||
Example: \texttt{/etc/init.d/httpd}
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
#!/bin/sh /etc/rc.common
|
|
||||||
# Copyright (C) 2006 OpenWrt.org
|
|
||||||
|
|
||||||
START=50
|
|
||||||
start() {
|
|
||||||
[ -d /www ] && httpd -p 80 -h /www -r OpenWrt
|
|
||||||
}
|
|
||||||
|
|
||||||
stop() {
|
|
||||||
killall httpd
|
|
||||||
}
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
as you can see, the script does not actually parse the command line arguments itself.
|
|
||||||
This is done by the wrapper script \texttt{/etc/rc.common}.
|
|
||||||
|
|
||||||
\texttt{start()} and \texttt{stop()} are the basic functions, which almost any init
|
|
||||||
script should provide. \texttt{start()} is called when the user runs \texttt{/etc/init.d/httpd start}
|
|
||||||
or (if the script is enabled and does not override this behavior) at system boot time.
|
|
||||||
|
|
||||||
Enabling and disabling init scripts is done by running \texttt{/etc/init.d/\textit{name} enable}
|
|
||||||
or \texttt{/etc/init.d/\textit{name} disable}. This creates or removes symbolic links to the
|
|
||||||
init script in \texttt{/etc/rc.d}, which is processed by \texttt{/etc/init.d/rcS} at boot time.
|
|
||||||
|
|
||||||
The order in which these scripts are run is defined in the variable \texttt{START} in the init
|
|
||||||
script. Changing it requires running \texttt{/etc/init.d/\textit{name} enable} again.
|
|
||||||
|
|
||||||
You can also override these standard init script functions:
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{boot()} \\
|
|
||||||
Commands to be run at boot time. Defaults to \texttt{start()}
|
|
||||||
|
|
||||||
\item \texttt{restart()} \\
|
|
||||||
Restart your service. Defaults to \texttt{stop(); start()}
|
|
||||||
|
|
||||||
\item \texttt{reload()} \\
|
|
||||||
Reload the configuration files for your service. Defaults to \texttt{restart()}
|
|
||||||
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
You can also add custom commands by creating the appropriate functions and referencing them
|
|
||||||
in the \texttt{EXTRA\_COMMANDS} variable. Helptext is added in \texttt{EXTRA\_HELP}.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
status() {
|
|
||||||
# print the status info
|
|
||||||
}
|
|
||||||
|
|
||||||
EXTRA_COMMANDS="status"
|
|
||||||
EXTRA_HELP=" status Print the status of the service"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
|
|
@ -1,55 +0,0 @@
|
||||||
\subsubsection{Using the network scripts}
|
|
||||||
|
|
||||||
To be able to access the network functions, you need to include
|
|
||||||
the necessary shell scripts by running:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
. /lib/functions.sh # common functions
|
|
||||||
include /lib/network # include /lib/network/*.sh
|
|
||||||
scan_interfaces # read and parse the network config
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
Some protocols, such as PPP might change the configured interface names
|
|
||||||
at run time (e.g. \texttt{eth0} => \texttt{ppp0} for PPPoE). That's why you have to run
|
|
||||||
\texttt{scan\_interfaces} instead of reading the values from the config directly.
|
|
||||||
After running \texttt{scan\_interfaces}, the \texttt{'ifname'} option will always contain
|
|
||||||
the effective interface name (which is used for IP traffic) and if the
|
|
||||||
physical device name differs from it, it will be stored in the \texttt{'device'}
|
|
||||||
option.
|
|
||||||
That means that running \texttt{config\_get lan ifname}
|
|
||||||
after \texttt{scan\_interfaces} might not return the same result as running it before.
|
|
||||||
|
|
||||||
After running \texttt{scan\_interfaces}, the following functions are available:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item{\texttt{find\_config \textit{interface}}} \\
|
|
||||||
looks for a network configuration that includes
|
|
||||||
the specified network interface.
|
|
||||||
|
|
||||||
\item{\texttt{setup\_interface \textit{interface [config] [protocol]}}} \\
|
|
||||||
will set up the specified interface, optionally overriding the network configuration
|
|
||||||
name or the protocol that it uses.
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\subsubsection{Writing protocol handlers}
|
|
||||||
|
|
||||||
You can add custom protocol handlers (e.g: PPPoE, PPPoA, ATM, PPTP ...)
|
|
||||||
by adding shell scripts to \texttt{/lib/network}. They provide the following
|
|
||||||
two shell functions:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
scan_<protocolname>() {
|
|
||||||
local config="$1"
|
|
||||||
# change the interface names if necessary
|
|
||||||
}
|
|
||||||
|
|
||||||
setup_interface_<protocolname>() {
|
|
||||||
local interface="$1"
|
|
||||||
local config="$2"
|
|
||||||
# set up the interface
|
|
||||||
}
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\texttt{scan\_\textit{protocolname}} is optional and only necessary if your protocol
|
|
||||||
uses a custom device, e.g. a tunnel or a PPP device.
|
|
||||||
|
|
||||||
231
docs/network.tex
231
docs/network.tex
|
|
@ -1,231 +0,0 @@
|
||||||
The network configuration is stored in \texttt{/etc/config/network}
|
|
||||||
and is divided into interface configurations.
|
|
||||||
Each interface configuration either refers directly to an ethernet/wifi
|
|
||||||
interface (\texttt{eth0}, \texttt{wl0}, ..) or to a bridge containing multiple interfaces.
|
|
||||||
It looks like this:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config interface "lan"
|
|
||||||
option ifname "eth0"
|
|
||||||
option proto "static"
|
|
||||||
option ipaddr "192.168.1.1"
|
|
||||||
option netmask "255.255.255.0"
|
|
||||||
option gateway "192.168.1.254"
|
|
||||||
option dns "192.168.1.254"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\texttt{ifname} specifies the Linux interface name.
|
|
||||||
If you want to use bridging on one or more interfaces, set \texttt{ifname} to a list
|
|
||||||
of interfaces and add:
|
|
||||||
\begin{Verbatim}
|
|
||||||
option type "bridge"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
It is possible to use VLAN tagging on an interface simply by adding the VLAN IDs
|
|
||||||
to it, e.g. \texttt{eth0.15}. These can be nested as well. See the switch section for
|
|
||||||
this.
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config interface
|
|
||||||
option ifname "eth0.15"
|
|
||||||
option proto "none"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
This sets up a simple static configuration for \texttt{eth0}. \texttt{proto} specifies the
|
|
||||||
protocol used for the interface. The default image usually provides \texttt{'none'}
|
|
||||||
\texttt{'static'}, \texttt{'dhcp'} and \texttt{'pppoe'}. Others can be added by installing additional
|
|
||||||
packages.
|
|
||||||
|
|
||||||
When using the \texttt{'static'} method like in the example, the options \texttt{ipaddr} and
|
|
||||||
\texttt{netmask} are mandatory, while \texttt{gateway} and \texttt{dns} are optional.
|
|
||||||
You can specify more than one DNS server, separated with spaces:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config interface "lan"
|
|
||||||
option ifname "eth0"
|
|
||||||
option proto "static"
|
|
||||||
...
|
|
||||||
option dns "192.168.1.254 192.168.1.253" (optional)
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
DHCP currently only accepts \texttt{ipaddr} (IP address to request from the server)
|
|
||||||
and \texttt{hostname} (client hostname identify as) - both are optional.
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config interface "lan"
|
|
||||||
option ifname "eth0"
|
|
||||||
option proto "dhcp"
|
|
||||||
option ipaddr "192.168.1.1" (optional)
|
|
||||||
option hostname "openwrt" (optional)
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
PPP based protocols (\texttt{pppoe}, \texttt{pptp}, ...) accept these options:
|
|
||||||
\begin{itemize}
|
|
||||||
\item{username} \\
|
|
||||||
The PPP username (usually with PAP authentication)
|
|
||||||
\item{password} \\
|
|
||||||
The PPP password
|
|
||||||
\item{keepalive} \\
|
|
||||||
Ping the PPP server (using LCP). The value of this option
|
|
||||||
specifies the maximum number of failed pings before reconnecting.
|
|
||||||
The ping interval defaults to 5, but can be changed by appending
|
|
||||||
",<interval>" to the keepalive value
|
|
||||||
\item{demand} \\
|
|
||||||
Use Dial on Demand (value specifies the maximum idle time.
|
|
||||||
\item{server: (pptp)} \\
|
|
||||||
The remote pptp server IP
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
For all protocol types, you can also specify the MTU by using the \texttt{mtu} option.
|
|
||||||
A sample PPPoE config would look like this:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config interface "lan"
|
|
||||||
option ifname "eth0"
|
|
||||||
option proto "pppoe"
|
|
||||||
option username "username"
|
|
||||||
option password "openwrt"
|
|
||||||
option mtu "1492" (optional)
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\subsubsection{Setting up static routes}
|
|
||||||
|
|
||||||
You can set up static routes for a specific interface that will be brought up
|
|
||||||
after the interface is configured.
|
|
||||||
|
|
||||||
Simply add a config section like this:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config route foo
|
|
||||||
option interface "lan"
|
|
||||||
option target "1.1.1.0"
|
|
||||||
option netmask "255.255.255.0"
|
|
||||||
option gateway "192.168.1.1"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
The name for the route section is optional, the \texttt{interface}, \texttt{target} and
|
|
||||||
\texttt{gateway} options are mandatory.
|
|
||||||
Leaving out the \texttt{netmask} option will turn the route into a host route.
|
|
||||||
|
|
||||||
\subsubsection{Setting up the switch (broadcom only)}
|
|
||||||
|
|
||||||
The switch configuration is set by adding a \texttt{'switch'} config section.
|
|
||||||
Example:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config switch "eth0"
|
|
||||||
option vlan0 "1 2 3 4 5*"
|
|
||||||
option vlan1 "0 5"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
On Broadcom hardware the section name needs to be eth0, as the switch driver
|
|
||||||
does not detect the switch on any other physical device.
|
|
||||||
Every vlan option needs to have the name vlan<n> where <n> is the VLAN number
|
|
||||||
as used in the switch driver.
|
|
||||||
As value it takes a list of ports with these optional suffixes:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item{\texttt{'*'}:}
|
|
||||||
Set the default VLAN (PVID) of the Port to the current VLAN
|
|
||||||
\item{\texttt{'u'}:}
|
|
||||||
Force the port to be untagged
|
|
||||||
\item{\texttt{'t'}:}
|
|
||||||
Force the port to be tagged
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
The CPU port defaults to tagged, all other ports to untagged.
|
|
||||||
On Broadcom hardware the CPU port is always 5. The other ports may vary with
|
|
||||||
different hardware.
|
|
||||||
|
|
||||||
For instance, if you wish to have 3 vlans, like one 3-port switch, 1 port in a
|
|
||||||
DMZ, and another one as your WAN interface, use the following configuration :
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config switch "eth0"
|
|
||||||
option vlan0 "1 2 3 5*"
|
|
||||||
option vlan1 "0 5"
|
|
||||||
option vlan2 "4 5"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
Three interfaces will be automatically created using this switch layout :
|
|
||||||
\texttt{eth0.0} (vlan0), \texttt{eth0.1} (vlan1) and \texttt{eth0.2} (vlan2).
|
|
||||||
You can then assign those interfaces to a custom network configuration name
|
|
||||||
like \texttt{lan}, \texttt{wan} or \texttt{dmz} for instance.
|
|
||||||
|
|
||||||
\subsubsection{Setting up the switch (swconfig)}
|
|
||||||
|
|
||||||
\emph{swconfig} based configurations have a different structure with one extra
|
|
||||||
section per vlan. The example below shows a typical configuration:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config 'switch' 'eth0'
|
|
||||||
option 'reset' '1'
|
|
||||||
option 'enable_vlan' '1'
|
|
||||||
|
|
||||||
config 'switch_vlan' 'eth0_1'
|
|
||||||
option 'device' 'eth0'
|
|
||||||
option 'vlan' '1'
|
|
||||||
option 'ports' '0 1 2 3 5t'
|
|
||||||
|
|
||||||
config 'switch_vlan' 'eth0_2'
|
|
||||||
option 'device' 'eth0'
|
|
||||||
option 'vlan' '2'
|
|
||||||
option 'ports' '4 5t'
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\subsubsection{Setting up IPv6 connectivity}
|
|
||||||
|
|
||||||
OpenWrt supports IPv6 connectivity using PPP, Tunnel brokers or static
|
|
||||||
assignment.
|
|
||||||
|
|
||||||
If you use PPP, IPv6 will be setup using IP6CP and there is nothing to
|
|
||||||
configure.
|
|
||||||
|
|
||||||
To setup an IPv6 tunnel to a tunnel broker, you can install the
|
|
||||||
\texttt{6scripts} package and edit the \texttt{/etc/config/6tunnel}
|
|
||||||
file and change the settings accordingly :
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config 6tunnel
|
|
||||||
option tnlifname 'sixbone'
|
|
||||||
option remoteip4 '1.0.0.1'
|
|
||||||
option localip4 '1.0.0.2'
|
|
||||||
option localip6 '2001::DEAD::BEEF::1'
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item{\texttt{'tnlifname'}:}
|
|
||||||
Set the interface name of the IPv6 in IPv4 tunnel
|
|
||||||
\item{\texttt{'remoteip4'}:}
|
|
||||||
IP address of the remote end to establish the 6in4 tunnel.
|
|
||||||
This address is given by the tunnel broker
|
|
||||||
\item{\texttt{'localip4'}:}
|
|
||||||
IP address of your router to establish the 6in4 tunnel.
|
|
||||||
It will usually match your WAN IP address.
|
|
||||||
\item{\texttt{'localip6'}:}
|
|
||||||
IPv6 address to setup on your tunnel side
|
|
||||||
This address is given by the tunnel broker
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
Using the same package you can also setup an IPv6 bridged connection:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config 6bridge
|
|
||||||
option bridge 'br6'
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
By default the script bridges the WAN interface with the LAN interface
|
|
||||||
and uses ebtables to filter anything that is not IPv6 on the bridge.
|
|
||||||
This configuration is particularly useful if your router is not
|
|
||||||
IPv6 ND proxy capable (see: http://www.rfc-archive.org/getrfc.php?rfc=4389).
|
|
||||||
|
|
||||||
IPv6 static addressing is also supported using a similar setup as
|
|
||||||
IPv4 but with the \texttt{ip6} prefixing (when applicable).
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config interface "lan"
|
|
||||||
option ifname "eth0"
|
|
||||||
option proto "static"
|
|
||||||
option ip6addr "fe80::200:ff:fe00:0/64"
|
|
||||||
option ip6gw "2001::DEAF:BEE:1"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
@ -1,10 +0,0 @@
|
||||||
\ProvidesPackage{openwrt}
|
|
||||||
|
|
||||||
\usepackage[latin9]{inputenc}
|
|
||||||
\usepackage[bookmarks=true color=blue colorlinks=true]{hyperref}
|
|
||||||
\usepackage[T1]{fontenc}
|
|
||||||
\usepackage{ae,aecompl,aeguill}
|
|
||||||
\usepackage{fancyvrb}
|
|
||||||
\usepackage{enumerate}
|
|
||||||
\setlength{\parindent}{0pt}
|
|
||||||
\setlength{\parskip}\medskipamount
|
|
||||||
|
|
@ -1,41 +0,0 @@
|
||||||
\documentclass[a4paper]{book}
|
|
||||||
|
|
||||||
\usepackage{openwrt}
|
|
||||||
|
|
||||||
\begin{document}
|
|
||||||
\tableofcontents
|
|
||||||
\chapter{The Router}
|
|
||||||
\section{Getting started}
|
|
||||||
\subsection{Installation}
|
|
||||||
\subsection{Initial configuration}
|
|
||||||
\subsection{Failsafe mode}
|
|
||||||
\section{Configuring OpenWrt}
|
|
||||||
\subsection{Network}
|
|
||||||
\input{network}
|
|
||||||
\subsection{Wireless}
|
|
||||||
\input{wireless}
|
|
||||||
\section{Advanced configuration}
|
|
||||||
\input{config}
|
|
||||||
\subsection{Hotplug}
|
|
||||||
\subsection{Init scripts}
|
|
||||||
\input{init-scripts}
|
|
||||||
\subsection{Network scripts}
|
|
||||||
\input{network-scripts}
|
|
||||||
\chapter{Development issues}
|
|
||||||
\section{The build system}
|
|
||||||
\input{build}
|
|
||||||
\section{Extra tools}
|
|
||||||
\subsection{Image Builder}
|
|
||||||
\subsection{SDK}
|
|
||||||
\section{Working with OpenWrt}
|
|
||||||
\input{working}
|
|
||||||
\section{Adding platform support}
|
|
||||||
\input{adding}
|
|
||||||
\section{Debugging and debricking}
|
|
||||||
\input{debugging}
|
|
||||||
\section{Reporting bugs}
|
|
||||||
\subsection{Using the Trac ticket system}
|
|
||||||
\input{bugs}
|
|
||||||
\section{Submitting patches}
|
|
||||||
\input{submitting-patches}
|
|
||||||
\end{document}
|
|
||||||
|
|
@ -1,53 +0,0 @@
|
||||||
\subsection{How to contribute}
|
|
||||||
OpenWrt is constantly being improved. We'd like as many people to contribute
|
|
||||||
to this as we can get. If you find a change useful, by all means try to get
|
|
||||||
it incorporated into the project. This should improve OpenWrt and it should
|
|
||||||
help carry your changes forward into future versions
|
|
||||||
|
|
||||||
This section tries to lay out a procedure to enable people to submit patches
|
|
||||||
in a way that is most effective for all concerned.
|
|
||||||
|
|
||||||
It is important to do all these steps repeatedly:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \textit{listen} to what other people think.
|
|
||||||
\item \textit{talk} explaining what problem you are addressing and your
|
|
||||||
proposed solution.
|
|
||||||
\item \textit{do} write useful patches including documentation.
|
|
||||||
\item \textit{test. test. test.}
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\subsection{Where to listen and talk}
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item google to find things related to your problem
|
|
||||||
\item Mailing lists: \href{http://lists.openwrt.org/}{http://lists.openwrt.org/}
|
|
||||||
\item Wiki: check the wiki: \href{http://wiki.openwrt.org/OpenWrtDocs}{http://wiki.openwrt.org/OpenWrtDocs}
|
|
||||||
\item Forum: \href{http://forum.openwrt.org/}{http://forum.openwrt.org/}
|
|
||||||
\item IRC: \texttt{irc.freenode.net}, channels \texttt{\#openwrt} and
|
|
||||||
\texttt{\#openwrt-devel}
|
|
||||||
\item TRAC: \href{https://dev.openwrt.org/}{https://dev.openwrt.org/} the issue/bug/change tracking system
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
It is often best to document what you are doing before you do it. The process
|
|
||||||
of documentation often exposes possible improvements. Keep your documentation
|
|
||||||
up to date.
|
|
||||||
|
|
||||||
\subsection{Patch Submission Process}
|
|
||||||
\begin{enumerate}
|
|
||||||
\item Use git or svn to create a patch. Creating patches manually with
|
|
||||||
\textit{diff -urN} also works, but is usually unnecessary.
|
|
||||||
\item Send a mail to openwrt-devel@lists.openwrt.org with the following contents:
|
|
||||||
\begin{enumerate}
|
|
||||||
\item \texttt{[PATCH] <short description>} in the Subject, followed by:
|
|
||||||
\item (optional) a longer description of your patch in the message body
|
|
||||||
\item \texttt{Signed-off-by: Your name <your@email.address>}
|
|
||||||
\item Your actual patch, inline, not word wrapped or whitespace mangled.
|
|
||||||
\end{enumerate}
|
|
||||||
\item Please read \href{http://kerneltrap.org/Linux/Email\_Clients\_and\_Patches}{http://kerneltrap.org/Linux/Email\_Clients\_and\_Patches}
|
|
||||||
to find out how to make sure your email client doesn't destroy your patch.
|
|
||||||
\item Please use your real name and email address in the \texttt{Signed-off-by}
|
|
||||||
line, following the same guidelines as in the \href{http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/SubmittingPatches;h=681e2b36195c98ea5271b76383b3a574b190b04f;hb=HEAD}{Linux Kernel patch submission guidelines}
|
|
||||||
\item Example of a properly formatted patch submission: \\
|
|
||||||
\href{http://lists.openwrt.org/pipermail/openwrt-devel/2007-November/001334.html}{http://lists.openwrt.org/pipermail/openwrt-devel/2007-November/001334.html}
|
|
||||||
\end{enumerate}
|
|
||||||
|
|
@ -1,492 +0,0 @@
|
||||||
The WiFi settings are configured in the file \texttt{/etc/config/wireless}
|
|
||||||
(currently supported on Broadcom, Atheros and mac80211). When booting the router for the first time
|
|
||||||
it should detect your card and create a sample configuration file. By default '\texttt{option network lan}' is
|
|
||||||
commented. This prevents unsecured sharing of the network over the wireless interface.
|
|
||||||
|
|
||||||
Each wireless driver has its own configuration script in \texttt{/lib/wifi/driver\_name.sh} which handles
|
|
||||||
driver specific options and configurations. This script is also calling driver specific binaries like wlc for
|
|
||||||
Broadcom, or hostapd and wpa\_supplicant for atheros and mac80211.
|
|
||||||
|
|
||||||
The reason for using such architecture, is that it abstracts the driver configuration.
|
|
||||||
|
|
||||||
\paragraph{Generic Broadcom wireless config:}
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config wifi-device "wl0"
|
|
||||||
option type "broadcom"
|
|
||||||
option channel "5"
|
|
||||||
|
|
||||||
config wifi-iface
|
|
||||||
option device "wl0"
|
|
||||||
# option network lan
|
|
||||||
option mode "ap"
|
|
||||||
option ssid "OpenWrt"
|
|
||||||
option hidden "0"
|
|
||||||
option encryption "none"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\paragraph{Generic Atheros wireless config:}
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config wifi-device "wifi0"
|
|
||||||
option type "atheros"
|
|
||||||
option channel "5"
|
|
||||||
option hwmode "11g"
|
|
||||||
|
|
||||||
config wifi-iface
|
|
||||||
option device "wifi0"
|
|
||||||
# option network lan
|
|
||||||
option mode "ap"
|
|
||||||
option ssid "OpenWrt"
|
|
||||||
option hidden "0"
|
|
||||||
option encryption "none"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\paragraph{Generic mac80211 wireless config:}
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config wifi-device "wifi0"
|
|
||||||
option type "mac80211"
|
|
||||||
option channel "5"
|
|
||||||
|
|
||||||
config wifi-iface
|
|
||||||
option device "wlan0"
|
|
||||||
# option network lan
|
|
||||||
option mode "ap"
|
|
||||||
option ssid "OpenWrt"
|
|
||||||
option hidden "0"
|
|
||||||
option encryption "none"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\paragraph{Generic multi-radio Atheros wireless config:}
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config wifi-device wifi0
|
|
||||||
option type atheros
|
|
||||||
option channel 1
|
|
||||||
|
|
||||||
config wifi-iface
|
|
||||||
option device wifi0
|
|
||||||
# option network lan
|
|
||||||
option mode ap
|
|
||||||
option ssid OpenWrt_private
|
|
||||||
option hidden 0
|
|
||||||
option encryption none
|
|
||||||
|
|
||||||
config wifi-device wifi1
|
|
||||||
option type atheros
|
|
||||||
option channel 11
|
|
||||||
|
|
||||||
config wifi-iface
|
|
||||||
option device wifi1
|
|
||||||
# option network lan
|
|
||||||
option mode ap
|
|
||||||
option ssid OpenWrt_public
|
|
||||||
option hidden 1
|
|
||||||
option encryption none
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
There are two types of config sections in this file. The '\texttt{wifi-device}' refers to
|
|
||||||
the physical wifi interface and '\texttt{wifi-iface}' configures a virtual interface on top
|
|
||||||
of that (if supported by the driver).
|
|
||||||
|
|
||||||
A full outline of the wireless configuration file with description of each field:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config wifi-device wifi device name
|
|
||||||
option type broadcom, atheros, mac80211
|
|
||||||
option country us, uk, fr, de, etc.
|
|
||||||
option channel 1-14
|
|
||||||
option maxassoc 1-128 (broadcom only)
|
|
||||||
option distance 1-n (meters)
|
|
||||||
option hwmode 11b, 11g, 11a, 11bg (atheros, mac80211)
|
|
||||||
option rxantenna 0,1,2 (atheros, broadcom)
|
|
||||||
option txantenna 0,1,2 (atheros, broadcom)
|
|
||||||
option txpower transmission power in dBm
|
|
||||||
|
|
||||||
config wifi-iface
|
|
||||||
option network the interface you want wifi to bridge with
|
|
||||||
option device wifi0, wifi1, wifi2, wifiN
|
|
||||||
option mode ap, sta, adhoc, monitor, mesh, or wds
|
|
||||||
option txpower (deprecated) transmission power in dBm
|
|
||||||
option ssid ssid name
|
|
||||||
option bssid bssid address
|
|
||||||
option encryption none, wep, psk, psk2, wpa, wpa2
|
|
||||||
option key encryption key
|
|
||||||
option key1 key 1
|
|
||||||
option key2 key 2
|
|
||||||
option key3 key 3
|
|
||||||
option key4 key 4
|
|
||||||
option passphrase 0,1
|
|
||||||
option server ip address
|
|
||||||
option port port
|
|
||||||
option hidden 0,1
|
|
||||||
option isolate 0,1 (broadcom)
|
|
||||||
option doth 0,1 (atheros, broadcom)
|
|
||||||
option wmm 0,1 (atheros, broadcom)
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\paragraph{Options for the \texttt{wifi-device}:}
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{type} \\
|
|
||||||
The driver to use for this interface.
|
|
||||||
|
|
||||||
\item \texttt{country} \\
|
|
||||||
The country code used to determine the regulatory settings.
|
|
||||||
|
|
||||||
\item \texttt{channel} \\
|
|
||||||
The wifi channel (e.g. 1-14, depending on your country setting).
|
|
||||||
|
|
||||||
\item \texttt{maxassoc} \\
|
|
||||||
Optional: Maximum number of associated clients. This feature is supported only on the Broadcom chipsets.
|
|
||||||
|
|
||||||
\item \texttt{distance} \\
|
|
||||||
Optional: Distance between the ap and the furthest client in meters. This feature is supported only on the Atheros chipsets.
|
|
||||||
|
|
||||||
\item \texttt{mode} \\
|
|
||||||
The frequency band (\texttt{b}, \texttt{g}, \texttt{bg}, \texttt{a}). This feature is only supported on the Atheros chipsets.
|
|
||||||
|
|
||||||
\item \texttt{diversity} \\
|
|
||||||
Optional: Enable diversity for the Wi-Fi device. This feature is supported only on the Atheros chipsets.
|
|
||||||
|
|
||||||
\item \texttt{rxantenna} \\
|
|
||||||
Optional: Antenna identifier (0, 1 or 2) for reception. This feature is supported by Atheros and some Broadcom chipsets.
|
|
||||||
|
|
||||||
\item \texttt{txantenna} \\
|
|
||||||
Optional: Antenna identifier (0, 1 or 2) for emission. This feature is supported by Atheros and some Broadcom chipsets.
|
|
||||||
|
|
||||||
\item \texttt{txpower}
|
|
||||||
Set the transmission power to be used. The amount is specified in dBm.
|
|
||||||
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\paragraph{Options for the \texttt{wifi-iface}:}
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{network} \\
|
|
||||||
Selects the interface section from \texttt{/etc/config/network} to be
|
|
||||||
used with this interface
|
|
||||||
|
|
||||||
\item \texttt{device} \\
|
|
||||||
Set the wifi device name.
|
|
||||||
|
|
||||||
\item \texttt{mode} \\
|
|
||||||
Operating mode:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{ap} \\
|
|
||||||
Access point mode
|
|
||||||
|
|
||||||
\item \texttt{sta} \\
|
|
||||||
Client mode
|
|
||||||
|
|
||||||
\item \texttt{adhoc} \\
|
|
||||||
Ad-Hoc mode
|
|
||||||
|
|
||||||
\item \texttt{monitor} \\
|
|
||||||
Monitor mode
|
|
||||||
|
|
||||||
\item \texttt{mesh} \\
|
|
||||||
Mesh Point mode (802.11s)
|
|
||||||
|
|
||||||
\item \texttt{wds} \\
|
|
||||||
WDS point-to-point link
|
|
||||||
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\item \texttt{ssid}
|
|
||||||
Set the SSID to be used on the wifi device.
|
|
||||||
|
|
||||||
\item \texttt{bssid}
|
|
||||||
Set the BSSID address to be used for wds to set the mac address of the other wds unit.
|
|
||||||
|
|
||||||
\item \texttt{txpower}
|
|
||||||
(Deprecated, set in wifi-device) Set the transmission power to be used. The amount is specified in dBm.
|
|
||||||
|
|
||||||
\item \texttt{encryption} \\
|
|
||||||
Encryption setting. Accepts the following values:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{none}
|
|
||||||
\item \texttt{wep}
|
|
||||||
\item \texttt{psk}, \texttt{psk2} \\
|
|
||||||
WPA(2) Pre-shared Key
|
|
||||||
|
|
||||||
\item \texttt{wpa}, \texttt{wpa2} \\
|
|
||||||
WPA(2) RADIUS
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\item \texttt{key, key1, key2, key3, key4} (wep, wpa and psk) \\
|
|
||||||
WEP key, WPA key (PSK mode) or the RADIUS shared secret (WPA RADIUS mode)
|
|
||||||
|
|
||||||
\item \texttt{passphrase} (wpa) \\
|
|
||||||
0 treats the wpa psk as a text passphrase; 1 treats wpa psk as
|
|
||||||
encoded passphrase. You can generate an encoded passphrase with
|
|
||||||
the wpa\_passphrase utility. This is especially useful if your
|
|
||||||
passphrase contains special characters. This option only works
|
|
||||||
when using mac80211 or atheros type devices.
|
|
||||||
|
|
||||||
\item \texttt{server} (wpa) \\
|
|
||||||
The RADIUS server ip address
|
|
||||||
|
|
||||||
\item \texttt{port} (wpa) \\
|
|
||||||
The RADIUS server port (defaults to 1812)
|
|
||||||
|
|
||||||
\item \texttt{hidden} \\
|
|
||||||
0 broadcasts the ssid; 1 disables broadcasting of the ssid
|
|
||||||
|
|
||||||
\item \texttt{isolate} \\
|
|
||||||
Optional: Isolation is a mode usually set on hotspots that limits the clients to communicate only with the AP and not with other wireless clients.
|
|
||||||
0 disables ap isolation (default); 1 enables ap isolation.
|
|
||||||
|
|
||||||
\item \texttt{doth} \\
|
|
||||||
Optional: Toggle 802.11h mode.
|
|
||||||
0 disables 802.11h (default); 1 enables it.
|
|
||||||
|
|
||||||
\item \texttt{wmm} \\
|
|
||||||
Optional: Toggle 802.11e mode.
|
|
||||||
0 disables 802.11e (default); 1 enables it.
|
|
||||||
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\paragraph{Mesh Point}
|
|
||||||
|
|
||||||
Mesh Point (802.11s) is only supported by some mac80211 drivers. It requires the iw package
|
|
||||||
to be installed to setup mesh links. OpenWrt creates mshN mesh point interfaces. A sample
|
|
||||||
configuration looks like this:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config wifi-device "wlan0"
|
|
||||||
option type "mac80211"
|
|
||||||
option channel "5"
|
|
||||||
|
|
||||||
config wifi-iface
|
|
||||||
option device "wlan0"
|
|
||||||
option network lan
|
|
||||||
option mode "mesh"
|
|
||||||
option mesh_id "OpenWrt"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\paragraph{Wireless Distribution System}
|
|
||||||
|
|
||||||
WDS is a non-standard mode which will be working between two Broadcom devices for instance
|
|
||||||
but not between a Broadcom and Atheros device.
|
|
||||||
|
|
||||||
\subparagraph{Unencrypted WDS connections}
|
|
||||||
|
|
||||||
This configuration example shows you how to setup unencrypted WDS connections.
|
|
||||||
We assume that the peer configured as below as the BSSID ca:fe:ba:be:00:01
|
|
||||||
and the remote WDS endpoint ca:fe:ba:be:00:02 (option bssid field).
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config wifi-device "wl0"
|
|
||||||
option type "broadcom"
|
|
||||||
option channel "5"
|
|
||||||
|
|
||||||
config wifi-iface
|
|
||||||
option device "wl0"
|
|
||||||
option network lan
|
|
||||||
option mode "ap"
|
|
||||||
option ssid "OpenWrt"
|
|
||||||
option hidden "0"
|
|
||||||
option encryption "none"
|
|
||||||
|
|
||||||
config wifi-iface
|
|
||||||
option device "wl0"
|
|
||||||
option network lan
|
|
||||||
option mode wds
|
|
||||||
option ssid "OpenWrt WDS"
|
|
||||||
option bssid "ca:fe:ba:be:00:02"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\subparagraph{Encrypted WDS connections}
|
|
||||||
|
|
||||||
It is also possible to encrypt WDS connections. \texttt{psk}, \texttt{psk2} and
|
|
||||||
\texttt{psk+psk2} modes are supported. Configuration below is an example
|
|
||||||
configuration using Pre-Shared-Keys with AES algorithm.
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config wifi-device wl0
|
|
||||||
option type broadcom
|
|
||||||
option channel 5
|
|
||||||
|
|
||||||
config wifi-iface
|
|
||||||
option device "wl0"
|
|
||||||
option network lan
|
|
||||||
option mode ap
|
|
||||||
option ssid "OpenWrt"
|
|
||||||
option encryption psk2
|
|
||||||
option key "<key for clients>"
|
|
||||||
|
|
||||||
config wifi-iface
|
|
||||||
option device "wl0"
|
|
||||||
option network lan
|
|
||||||
option mode wds
|
|
||||||
option bssid ca:fe:ba:be:00:02
|
|
||||||
option ssid "OpenWrt WDS"
|
|
||||||
option encryption psk2
|
|
||||||
option key "<psk for WDS>"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\paragraph{802.1x configurations}
|
|
||||||
|
|
||||||
OpenWrt supports both 802.1x client and Access Point
|
|
||||||
configurations. 802.1x client is only working with
|
|
||||||
drivers supported by wpa-supplicant. Configuration
|
|
||||||
only supports EAP types TLS, TTLS or PEAP.
|
|
||||||
|
|
||||||
\subparagraph{EAP-TLS}
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config wifi-iface
|
|
||||||
option device "ath0"
|
|
||||||
option network lan
|
|
||||||
option ssid OpenWrt
|
|
||||||
option eap_type tls
|
|
||||||
option ca_cert "/etc/config/certs/ca.crt"
|
|
||||||
option priv_key "/etc/config/certs/priv.crt"
|
|
||||||
option priv_key_pwd "PKCS#12 passphrase"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\subparagraph{EAP-PEAP}
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
config wifi-iface
|
|
||||||
option device "ath0"
|
|
||||||
option network lan
|
|
||||||
option ssid OpenWrt
|
|
||||||
option eap_type peap
|
|
||||||
option ca_cert "/etc/config/certs/ca.crt"
|
|
||||||
option auth MSCHAPV2
|
|
||||||
option identity username
|
|
||||||
option password password
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\paragraph{Limitations:}
|
|
||||||
|
|
||||||
There are certain limitations when combining modes.
|
|
||||||
Only the following mode combinations are supported:
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item \textbf{Broadcom}: \\
|
|
||||||
\begin{itemize}
|
|
||||||
\item 1x \texttt{sta}, 0-3x \texttt{ap}
|
|
||||||
\item 1-4x \texttt{ap}
|
|
||||||
\item 1x \texttt{adhoc}
|
|
||||||
\item 1x \texttt{monitor}
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
WDS links can only be used in pure AP mode and cannot use WEP (except when sharing the
|
|
||||||
settings with the master interface, which is done automatically).
|
|
||||||
|
|
||||||
\item \textbf{Atheros}: \\
|
|
||||||
\begin{itemize}
|
|
||||||
\item 1x \texttt{sta}, 0-Nx \texttt{ap}
|
|
||||||
\item 1-Nx \texttt{ap}
|
|
||||||
\item 1x \texttt{adhoc}
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
N is the maximum number of VAPs that the module allows, it defaults to 4, but can be
|
|
||||||
changed by loading the module with the maxvaps=N parameter.
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
\paragraph{Adding a new driver configuration}
|
|
||||||
|
|
||||||
Since we currently only support thread different wireless drivers : Broadcom, Atheros and mac80211,
|
|
||||||
you might be interested in adding support for another driver like Ralink RT2x00,
|
|
||||||
Texas Instruments ACX100/111.
|
|
||||||
|
|
||||||
The driver specific script should be placed in \texttt{/lib/wifi/<driver>.sh} and has to
|
|
||||||
include several functions providing :
|
|
||||||
|
|
||||||
\begin{itemize}
|
|
||||||
\item detection of the driver presence
|
|
||||||
\item enabling/disabling the wifi interface(s)
|
|
||||||
\item configuration reading and setting
|
|
||||||
\item third-party programs calling (nas, supplicant)
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
Each driver script should append the driver to a global DRIVERS variable :
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
append DRIVERS "driver name"
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\subparagraph{\texttt{scan\_<driver>}}
|
|
||||||
|
|
||||||
This function will parse the \texttt{/etc/config/wireless} and make sure there
|
|
||||||
are no configuration incompatibilities, like enabling hidden SSIDS with ad-hoc mode
|
|
||||||
for instance. This can be more complex if your driver supports a lof of configuration
|
|
||||||
options. It does not change the state of the interface.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
\begin{Verbatim}
|
|
||||||
scan_dummy() {
|
|
||||||
local device="$1"
|
|
||||||
|
|
||||||
config_get vifs "$device" vifs
|
|
||||||
for vif in $vifs; do
|
|
||||||
# check config consistency for wifi-iface sections
|
|
||||||
done
|
|
||||||
# check mode combination
|
|
||||||
}
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\subparagraph{\texttt{enable\_<driver>}}
|
|
||||||
|
|
||||||
This function will bring up the wifi device and optionally create application specific
|
|
||||||
configuration files, e.g. for the WPA authenticator or supplicant.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
\begin{Verbatim}
|
|
||||||
enable_dummy() {
|
|
||||||
local device="$1"
|
|
||||||
|
|
||||||
config_get vifs "$device" vifs
|
|
||||||
for vif in $vifs; do
|
|
||||||
# bring up virtual interface belonging to
|
|
||||||
# the wifi-device "$device"
|
|
||||||
done
|
|
||||||
}
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\subparagraph{\texttt{disable\_<driver>}}
|
|
||||||
|
|
||||||
This function will bring down the wifi device and all its virtual interfaces (if supported).
|
|
||||||
|
|
||||||
Example:
|
|
||||||
\begin{Verbatim}
|
|
||||||
disable_dummy() {
|
|
||||||
local device="$1"
|
|
||||||
|
|
||||||
# bring down virtual interfaces belonging to
|
|
||||||
# "$device" regardless of whether they are
|
|
||||||
# configured or not. Don't rely on the vifs
|
|
||||||
# variable at this point
|
|
||||||
}
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\subparagraph{\texttt{detect\_<driver>}}
|
|
||||||
|
|
||||||
This function looks for interfaces that are usable with the driver. Template config sections
|
|
||||||
for new devices should be written to stdout. Must check for already existing config sections
|
|
||||||
belonging to the interfaces before creating new templates.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
\begin{Verbatim}
|
|
||||||
detect_dummy() {
|
|
||||||
[ wifi-device = "$(config_get dummydev type)" ] && return 0
|
|
||||||
cat <<EOF
|
|
||||||
config wifi-device dummydev
|
|
||||||
option type dummy
|
|
||||||
# REMOVE THIS LINE TO ENABLE WIFI:
|
|
||||||
option disabled 1
|
|
||||||
|
|
||||||
config wifi-iface
|
|
||||||
option device dummydev
|
|
||||||
option mode ap
|
|
||||||
option ssid OpenWrt
|
|
||||||
EOF
|
|
||||||
}
|
|
||||||
\end{Verbatim}
|
|
||||||
112
docs/working.tex
112
docs/working.tex
|
|
@ -1,112 +0,0 @@
|
||||||
The following section gives some tips and tricks on how to use efficiently
|
|
||||||
OpenWrt on a regular basis and for daily work.
|
|
||||||
|
|
||||||
\subsection{Compiling/recompiling components}
|
|
||||||
|
|
||||||
The buildroot allows you to recompile the full environment or only parts of it
|
|
||||||
like the toolchain, the kernel modules, the kernel or some packages.
|
|
||||||
|
|
||||||
For instance if you want to recompile the toolchain after you made any change to it
|
|
||||||
issue the following command:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
make toolchain/{clean,compile,install}
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
Which will clean, compile and install the toolchain. The command actually expands to the
|
|
||||||
following:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
make[1] toolchain/clean
|
|
||||||
make[2] -C toolchain/kernel-headers clean
|
|
||||||
make[2] -C toolchain/binutils clean
|
|
||||||
make[2] -C toolchain/gcc clean
|
|
||||||
make[2] -C toolchain/uClibc clean (glibc or eglibc when chosen)
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
Of course, you could only choose to recompile one or several of the toolchain components
|
|
||||||
(binutils, kernel-headers gcc, C library) individually.
|
|
||||||
|
|
||||||
The exact same idea works for packages:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
make package/busybox/{clean,compile,install}
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
will clean, compile and install busybox (if selected to be installed on the final rootfs).
|
|
||||||
|
|
||||||
Supposing that you made changes to the Linux kernel, but do not want to recompile everything,
|
|
||||||
you can recompile only the kernel modules by issuing:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
make target/linux/compile
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
To recompile the static part of the kernel use the following command:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
make target/linux/install
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
\subsection{Using quilt inside OpenWrt}
|
|
||||||
|
|
||||||
OpenWrt integrates quilt in order to ease the package, kernel and toolchain
|
|
||||||
patches maintenance when migrating over new versions of the software.
|
|
||||||
|
|
||||||
Quilt intends to replace an old workflow, where you would download the new
|
|
||||||
source file, create an original copy of it, an a working copy, then try to
|
|
||||||
apply by hand old patches and resolve conflicts manually. Additionnaly, using
|
|
||||||
quilt allows you to update and fold patches into other patches easily.
|
|
||||||
|
|
||||||
Quilt is used by default to apply Linux kernel patches, but not for the other
|
|
||||||
components (toolchain and packages).
|
|
||||||
|
|
||||||
\subsubsection{Using quilt with kernel patches}
|
|
||||||
|
|
||||||
Assuming that you have everything setup for your new kernel version:
|
|
||||||
\begin{itemize}
|
|
||||||
\item \texttt{LINUX\_VERSION} set in the target Makefile
|
|
||||||
\item config-2.6.x.y existing
|
|
||||||
\item patches-2.6.x.y containing the previous patches
|
|
||||||
\end{itemize}
|
|
||||||
|
|
||||||
Some patches are likely to fail since the vanilla kernel we are patching
|
|
||||||
received modifications so some hunks of the patches are no longer applying.
|
|
||||||
We will use quilt to get them applying cleanly again. Follow this procedure
|
|
||||||
whenever you want to upgrade the kernel using previous patches:
|
|
||||||
|
|
||||||
\begin{enumerate}
|
|
||||||
\item make target/linux/clean (removes the old version)
|
|
||||||
\item make target/linux/compile (uncompress the kernel and try to apply patches)
|
|
||||||
\item if patches failed to apply:
|
|
||||||
\item cd build\_dir/linux-target/linux-2.6.x.y
|
|
||||||
\item quilt push -a (to apply patches where quilt stopped)
|
|
||||||
\item quilt push -f (to force applying patches)
|
|
||||||
\item edit .rej files, apply the necessary changes to the files
|
|
||||||
\item remove .rej files
|
|
||||||
\item quilt refresh
|
|
||||||
\item repeat operation 3 and following until all patches have been applied
|
|
||||||
\item when all patches did apply cleanly: make target/linux/refresh
|
|
||||||
\end{enumerate}
|
|
||||||
|
|
||||||
Note that generic (target/linux/generic-2.6/linux-2.6.x/) patches can be found in
|
|
||||||
\texttt{build\_dir/linux-target/linux-2.6.x.y/patches/generic} and platform specific
|
|
||||||
patches in \texttt{build\_dir/linux-target/linux-2.6.x.y/patches/platform}.
|
|
||||||
|
|
||||||
\subsubsection{Using quilt with packages}
|
|
||||||
|
|
||||||
As we mentionned earlier, quilt is enabled by default for kernel patches, but not for
|
|
||||||
packages. If you want to use quilt in the same way, you should set the QUILT environment
|
|
||||||
variable to 1, e.g:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
make package/busybox/{clean,compile} QUILT=1
|
|
||||||
\end{Verbatim}
|
|
||||||
|
|
||||||
Will generate the patch series file and allow you to update patches just like we described
|
|
||||||
before in the kernel case. Note that once all patches apply cleanly you should refresh them
|
|
||||||
as well using the following command:
|
|
||||||
|
|
||||||
\begin{Verbatim}
|
|
||||||
make package/busybox/refresh QUILT=1
|
|
||||||
\end{Verbatim}
|
|
||||||
Loading…
Reference in a new issue