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>
+++ /dev/null
-*.log
-*.aux
-*.toc
-*.out
-*.lg
-*.dvi
-*.idv
-*.4ct
-*.4tc
-*.xref
-*.tmp
-*.dvi
-*.html
-*.css
-*.pdf
+++ /dev/null
-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
+++ /dev/null
-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}
+++ /dev/null
-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.
+++ /dev/null
-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}
+++ /dev/null
-\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.
-
+++ /dev/null
-Debugging hardware can be tricky especially when doing kernel and drivers
-development. It might become handy for you to add serial console to your
-device as well as using JTAG to debug your code.
-
-\subsection{Adding a serial port}
-
-Most routers come with an UART integrated into the System-on-chip
-and its pins are routed on the Printed Circuit Board to allow
-debugging, firmware replacement or serial device connection (like
-modems).
-
-Finding an UART on a router is fairly easy since it only needs at
-least 4 signals (without modem signaling) to work : VCC, GND, TX and
-RX. Since your router is very likely to have its I/O pins working at
-3.3V (TTL level), you will need a level shifter such as a Maxim MAX232
-to change the level from 3.3V to your computer level which is usually
-at 12V.
-
-To find out the serial console pins on the PCB, you will be looking
-for a populated or unpopulated 4-pin header, which can be far from
-the SoC (signals are relatively slow) and usually with tracks on
-the top or bottom layer of the PCB, and connected to the TX and RX.
-
-Once found, you can easily check where is GND, which is connected to
-the same ground layer than the power connector. VCC should be fixed
-at 3.3V and connected to the supply layer, TX is also at 3.3V level
-but using a multimeter as an ohm-meter and showing an infinite
-value between TX and VCC pins will tell you about them being different
-signals (or not). RX and GND are by default at 0V, so using the same
-technique you can determine the remaining pins like this.
-
-If you do not have a multimeter a simple trick that usually works is
-using a speaker or a LED to determine the 3.3V signals. Additionnaly
-most PCB designer will draw a square pad to indicate ping number 1.
-
-Once found, just interface your level shifter with the device and the
-serial port on the PC on the other side. Most common baudrates for the
-off-the-shelf devices are 9600, 38400 and 115200 with 8-bits data, no
-parity, 1-bit stop.
-
-\subsection{JTAG}
-
-JTAG stands for Joint Test Action Group, which is an IEEE workgroup
-defining an electrical interface for integrated circuit testing and
-programming.
-
-There is usually a JTAG automate integrated into your System-on-Chip
-or CPU which allows an external software, controlling the JTAG adapter
-to make it perform commands like reads and writes at arbitray locations.
-Additionnaly it can be useful to recover your devices if you erased the
-bootloader resident on the flash.
-
-Different CPUs have different automates behavior and reset sequence,
-most likely you will find ARM and MIPS CPUs, both having their standard
-to allow controlling the CPU behavior using JTAG.
-
-Finding JTAG connector on a PCB can be a little easier than finding the
-UART since most vendors leave those headers unpopulated after production.
-JTAG connectors are usually 12, 14, or 20-pins headers with one side of
-the connector having some signals at 3.3V and the other side being
-connected to GND.
+++ /dev/null
-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}
-
+++ /dev/null
-\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.
-
+++ /dev/null
-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}
+++ /dev/null
-\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
+++ /dev/null
-\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}
+++ /dev/null
-\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}
+++ /dev/null
-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}
+++ /dev/null
-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}
projects / openwrt / openwrt.git / commitdiff