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