ASR_BASE
Change-Id: Icf3719cc0afe3eeb3edc7fa80a2eb5199ca9dda1
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..7abd82e
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,14 @@
+*.log
+*.aux
+*.toc
+*.out
+*.lg
+*.dvi
+*.idv
+*.4ct
+*.4tc
+*.xref
+*.tmp
+*.dvi
+*.html
+*.css
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..c113d62
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,48 @@
+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
new file mode 100644
index 0000000..97547ac
--- /dev/null
+++ b/docs/adding.tex
@@ -0,0 +1,590 @@
+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 -9 -c $(KDIR)/vmlinux > $(KDIR)/vmlinux.bin.gz
+ $(STAGING_DIR_HOST)/bin/lzma e $(KDIR)/vmlinux $(KDIR)/vmlinux.bin.l7
+ dd if=$(KDIR)/vmlinux.bin.l7 of=$(BIN_DIR)/openwrt-$(BOARD)-vmlinux.lzma bs=65536 conv=sync
+ dd if=$(KDIR)/vmlinux.bin.gz of=$(BIN_DIR)/openwrt-$(BOARD)-vmlinux.gz bs=65536 conv=sync
+endef
+
+define Image/Build/squashfs
+ $(call prepare_generic_squashfs,$(KDIR)/root.squashfs)
+endef
+
+define Image/Build
+ $(call Image/Build/$(1))
+ dd if=$(KDIR)/root.$(1) of=$(BIN_DIR)/openwrt-$(BOARD)-root.$(1) bs=128k conv=sync
+
+ -$(STAGING_DIR_HOST)/bin/mkfwimage \
+ -B XS2 -v XS2.ar2316.OpenWrt \
+ -k $(BIN_DIR)/openwrt-$(BOARD)-vmlinux.lzma \
+ -r $(BIN_DIR)/openwrt-$(BOARD)-root.$(1) \
+ -o $(BIN_DIR)/openwrt-$(BOARD)-ubnt2-$(1).bin
+endef
+
+$(eval $(call BuildImage))
+
+\end{Verbatim}
+
+\begin{itemize}
+ \item \texttt{Image/BuildKernel} \\
+ This template defines changes to be made to the ELF kernel file
+ \item \texttt{Image/Build} \\
+ This template defines the final changes to apply to the rootfs and kernel, either combined or separated
+ firmware creation tools can be called here as well.
+\end{itemize}
diff --git a/docs/bugs.tex b/docs/bugs.tex
new file mode 100644
index 0000000..9c46b5a
--- /dev/null
+++ b/docs/bugs.tex
@@ -0,0 +1,52 @@
+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
new file mode 100644
index 0000000..6e1539a
--- /dev/null
+++ b/docs/build.tex
@@ -0,0 +1,594 @@
+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
new file mode 100644
index 0000000..08318b4
--- /dev/null
+++ b/docs/config.tex
@@ -0,0 +1,101 @@
+\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
new file mode 100644
index 0000000..2d2a5d3
--- /dev/null
+++ b/docs/debugging.tex
@@ -0,0 +1,61 @@
+Debugging hardware can be tricky especially when doing kernel and drivers
+development. It might become handy for you to add serial console to your
+device as well as using JTAG to debug your code.
+
+\subsection{Adding a serial port}
+
+Most routers come with an UART integrated into the System-on-chip
+and its pins are routed on the Printed Circuit Board to allow
+debugging, firmware replacement or serial device connection (like
+modems).
+
+Finding an UART on a router is fairly easy since it only needs at
+least 4 signals (without modem signaling) to work : VCC, GND, TX and
+RX. Since your router is very likely to have its I/O pins working at
+3.3V (TTL level), you will need a level shifter such as a Maxim MAX232
+to change the level from 3.3V to your computer level which is usually
+at 12V.
+
+To find out the serial console pins on the PCB, you will be looking
+for a populated or unpopulated 4-pin header, which can be far from
+the SoC (signals are relatively slow) and usually with tracks on
+the top or bottom layer of the PCB, and connected to the TX and RX.
+
+Once found, you can easily check where is GND, which is connected to
+the same ground layer than the power connector. VCC should be fixed
+at 3.3V and connected to the supply layer, TX is also at 3.3V level
+but using a multimeter as an ohm-meter and showing an infinite
+value between TX and VCC pins will tell you about them being different
+signals (or not). RX and GND are by default at 0V, so using the same
+technique you can determine the remaining pins like this.
+
+If you do not have a multimeter a simple trick that usually works is
+using a speaker or a LED to determine the 3.3V signals. Additionnaly
+most PCB designer will draw a square pad to indicate ping number 1.
+
+Once found, just interface your level shifter with the device and the
+serial port on the PC on the other side. Most common baudrates for the
+off-the-shelf devices are 9600, 38400 and 115200 with 8-bits data, no
+parity, 1-bit stop.
+
+\subsection{JTAG}
+
+JTAG stands for Joint Test Action Group, which is an IEEE workgroup
+defining an electrical interface for integrated circuit testing and
+programming.
+
+There is usually a JTAG automate integrated into your System-on-Chip
+or CPU which allows an external software, controlling the JTAG adapter
+to make it perform commands like reads and writes at arbitray locations.
+Additionnaly it can be useful to recover your devices if you erased the
+bootloader resident on the flash.
+
+Different CPUs have different automates behavior and reset sequence,
+most likely you will find ARM and MIPS CPUs, both having their standard
+to allow controlling the CPU behavior using JTAG.
+
+Finding JTAG connector on a PCB can be a little easier than finding the
+UART since most vendors leave those headers unpopulated after production.
+JTAG connectors are usually 12, 14, or 20-pins headers with one side of
+the connector having some signals at 3.3V and the other side being
+connected to GND.
diff --git a/docs/init-scripts.tex b/docs/init-scripts.tex
new file mode 100644
index 0000000..c8b0750
--- /dev/null
+++ b/docs/init-scripts.tex
@@ -0,0 +1,60 @@
+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/marvell/hardware/pxa1826_dkb_a.pdf b/docs/marvell/hardware/pxa1826_dkb_a.pdf
new file mode 100644
index 0000000..7d58ea5
--- /dev/null
+++ b/docs/marvell/hardware/pxa1826_dkb_a.pdf
Binary files differ
diff --git a/docs/marvell/hardware/pxa1826_dkb_b.pdf b/docs/marvell/hardware/pxa1826_dkb_b.pdf
new file mode 100644
index 0000000..278ce71
--- /dev/null
+++ b/docs/marvell/hardware/pxa1826_dkb_b.pdf
Binary files differ
diff --git a/docs/marvell/hardware/pxa1826_saar_n.pdf b/docs/marvell/hardware/pxa1826_saar_n.pdf
new file mode 100644
index 0000000..6b9e64a
--- /dev/null
+++ b/docs/marvell/hardware/pxa1826_saar_n.pdf
Binary files differ
diff --git a/docs/marvell/howto/add_new_profile.txt b/docs/marvell/howto/add_new_profile.txt
new file mode 100644
index 0000000..dff67fe
--- /dev/null
+++ b/docs/marvell/howto/add_new_profile.txt
@@ -0,0 +1,97 @@
+How to add new profile for a subtarget
+========================================
+There are serveral subtargets in the target/linux/mmp (pxa1826, asr1802s, asr1803...).
+Here we take 1826 (i.e. Nezha3) as a sample, others are similar.
+
+Basically a new profile is created for a new hardware board or a new product model.
+
+Steps needed:
+----------------------------------------------------------------------------
+1. Add a new profile entry in: "target/linux/mmp/pxa1826/profiles/marvell.mk"
+ For example:
+
+ "define Profile/NEZHA305
+ NAME:=NEZHA3-DKB Type A with Nand Flash
+ endef
+ $(eval $(call Profile,NEZHA305))
+ $(eval $(call Model,NEZHA305,pxa1826p305))
+ "
+
+ where NEZHA305 is your <profile_name>
+
+2. Create a defconfig file in "config/" with desired configuration.
+ Meanwhile, create specific obm and uboot codes.
+
+ The typical steps are
+ ~$ make distclean
+ ~$ ./scripts/feeds update -a
+ ~$ ./scripts/feeds install -a
+ ~$ vi package/boot/obm-mmp/Makefile //need to add profile specific obm
+ ~$ <add specific obm code and build instruction in Loader/Platforms/NZA3/DKB/make_loader_NZA3_LINUX.sh when necessary>
+ ~$ vi package/boot/uboot-mmp/Makefile //need to add profile specific board type in uboot if a new one used here
+ ~$ <add specific uboot code in uboot/board/Marvell/ and uboot/include/configs, also update board config in marvell/uboot/boards.cfg>
+ ~$ cp config/defconfig_pxa1826 .config
+ ~$ make menuconfig // choose the proper profile, bootloaders, pakcages,etc. then exit and save
+ ~$ cp .config config/defconfig_<ARCH_PROFILE>
+
+
+3. In "target/linux/mmp/image/Makefile":
+ Add new line: Image/BuildKernel/Profile/<profile_name>=$(call Image/Build/DTB,<dts_filename>)
+
+ and put it in:
+ "ifeq ($(CONFIG_TARGET_mmp_pxa1826),y)
+ Image/BuildKernel/Profile/NEZHA301=$(call Image/Build/DTB,pxa1826-dkb)
+ ... ...
+ Image/BuildKernel/Profile/NEZHA305=$(call Image/Build/DTB,pxa1826-p305)
+ Image/BuildKernel/Profile/<profile_name>=$(call Image/Build/DTB,<dts_filename>)
+ endif"
+
+4. In "rules.mk"
+ Add:
+ "ifeq ($(CONFIG_TARGET_mmp_pxa1826_<profile_name>),y)
+ export ARCH_PROFILE:=<profile_bin_dir_name>
+ export KERNEL_CONFIG_FILE_NAME_APPENDIX:=
+ #you can insert here any profile specific variables and use it in the openwrt makefiles
+ endif"
+
+5. Add dts file for the board.
+
+ Create <dts_filename>.dts and put in /marvell/linux/arch/arm/boot/dts.
+
+ Next, in arch/arm/boot/dts/Makefile, add "<dts_filename>.dtb" to create dtb file:
+
+ "dtb-$(CONFIG_CPU_PXA1826) += pxa1826-dkb.dtb \
+ <dts_filename>.dtb"
+
+6. Create the BLF files for under swd/NZA3/ for software download and OTA upgrade
+
+
+7. Create profile sepcific setting files and telephony images at locations below,
+
+ ~$ package/network/services/lte-telephony/files/nvm/<ARCH_PROFILE> //add fixed NV setting files, can't upgrade via OTA
+ ~$ package/network/services/lte-telephony/files/tel-<if>.config //add telephony config file and update its Makefile
+ ~$ <target/linux/mmp/files/mrd/> //add changeable NV setting files, which can be upgraded via OTA
+ ~$ <target/linux/mmp/pxa1826/oem_fs/> //OEM can also put upgradeable NV settings files here if there is OEM partition
+ ~$ <marvell/lte-telephony/cp/> //add new CP images if required
+
+8. build the profile images and fix any error during the building process
+
+==============================================================================================
+Additonal steps (optional):
+
+1. If you want to be able to identify your board from the console (e.g. TeraTerm),
+ Then, in file: "target/linux/mmp/base-files/lib/mmp.sh"
+ Function: mmp_board_detect()
+ You need to add a case for your board (profile).
+==============================================================================================
+Note:
+ On v2102 branch, the proman.sh script can help on
+ the step 1 to 4 above(i.e. only cover top repo changes) use existing profile as template,
+
+ Syntax: ./scripts/proman.sh add <template_profile> <chip> <name> <code>
+
+ e.g., ./scripts/proman.sh add asr1803p401 asr1828 KAGU 801
+
+ Affected files: rules.mk target/linux/mmp/Makefile target/linux/mmp/$CHIP config/defconfig_${CHIP}p$CODE
+
+ Limitations: obm-mmp, uboot-mmp and telephony packages need manual update.
diff --git a/docs/marvell/howto/asr1803_selinux_policy.pdf b/docs/marvell/howto/asr1803_selinux_policy.pdf
new file mode 100755
index 0000000..de353c3
--- /dev/null
+++ b/docs/marvell/howto/asr1803_selinux_policy.pdf
Binary files differ
diff --git a/docs/marvell/howto/creating_packages.pdf b/docs/marvell/howto/creating_packages.pdf
new file mode 100644
index 0000000..644c2c4
--- /dev/null
+++ b/docs/marvell/howto/creating_packages.pdf
Binary files differ
diff --git a/docs/marvell/howto/data_path_nat46.txt b/docs/marvell/howto/data_path_nat46.txt
new file mode 100644
index 0000000..9053beb
--- /dev/null
+++ b/docs/marvell/howto/data_path_nat46.txt
@@ -0,0 +1,141 @@
+How to config the NAT46 in datapath to use the XLAT(CLAT)
+========================================
+Here we take 1802s (i.e. NezhaS) as example, 1826 (i.e. Nezha3) is similar.
+The host PC system tested in this paper is Ubuntu 5.4.0-6Ubuntu 1~16.04.12.
+
+1, PIPE mode
+1) make kernel_menuconfig and select "DATA_PATH_NAT46" and save your new configuration.
+And then rebuild：make -j8 V=99
+
+2) Disable IPv6 in Ubuntu
+ "echo "net.ipv6.conf.all.disable_ipv6=1" >> /etc/sysctl.conf"
+ "sysctl -p"
+
+3) Redial using IPv6
+ "serial_client"
+ "AT+ZGDCONT=1,IPV6,GPRS"
+ "AT+ZGACT=1,1"
+ After this operation, you will not be able to access the IPv4 service and ping IPv4 will fail on the host side.
+
+4) NAT46 Configuration
+ First query the IPv6 global address and local IPv4 address of ccinet, use "cat /sys/kernel/mpipe/devices/all"
+ you will get some information like this:
+ device state type refcnt IP IPv6
+ lo Down pipe 2 0.0.0.0 ::/0
+ embms0 Down pipe 2 0.0.0.0 ::/0
+ ccinet0 Up4/6 pipe 2 10.180.250.252 240e:9a:83e:4a98::/64
+ ccinet1 Down pipe 2 0.0.0.0 ::/0
+ ccinet2 Down pipe 2 0.0.0.0 ::/0
+ ccinet3 Down pipe 2 0.0.0.0 ::/0
+ ccinet4 Down pipe 2 0.0.0.0 ::/0
+ ccinet5 Down pipe 2 0.0.0.0 ::/0
+ ccinet6 Down pipe 2 0.0.0.0 ::/0
+ ccinet7 Down pipe 2 0.0.0.0 ::/0
+ ip6tnl0 Down pipe 2 0.0.0.0 ::/0
+ tunl0 Down pipe 2 0.0.0.0 ::/0
+ usbnet0 Up4/6 lan 3 192.168.1.1 ::/0
+
+ "10.180.250.252" will serve as the IPv4 address of host and the local IPv4 address in NAT46,
+ and "240e:9a:83e:4a98::" will serve as the local IPv6 address in NAT46.
+ The detailed configuration is as follows:
+ "echo add nat46 | tee /sys/kernel/debug/tel/psd/data-pathv1/nat46_control"
+ "echo config nat46 local.v4 10.180.250.252/32 | tee /sys/kernel/debug/tel/psd/data-pathv1/nat46_control"
+ "echo config nat46 local.v6 240e:9a:83e:4a98::1/64 | tee /sys/kernel/debug/tel/psd/data-pathv1/nat46_control"
+ "echo config nat46 local.style RFC6052 | tee /sys/kernel/debug/tel/psd/data-pathv1/nat46_control"
+ 32 indicates the mask length of the local IPv4 address, 64 indicates the prefix length of an IPv6 address.
+
+ if the remote IPv6 server(PLAT) is "240e:eb:8001:e05::/96",
+ "echo config nat46 remote.v6 240e:eb:8001:e05::/96 | tee /sys/kernel/debug/tel/psd/data-pathv1/nat46_control"
+ "echo config nat46 remote.style RFC6052 | tee /sys/kernel/debug/tel/psd/data-pathv1/nat46_control"
+
+ the command "echo 1 > /sys/kernel/debug/tel/psd/data-pathv1/bypass_nat46" can be used to terminate the NAT46 translate.
+
+5) Host Configuration
+ "ifconfig enp0s26u1u1 10.180.250.252 netmask 255.255.255.0 up"
+ "route add default gw 10.180.250.3"
+
+6) Test
+ When use "echo 1 > /sys/kernel/debug/tel/psd/data-pathv1/bypass_nat46" to terminate the NAT46 translate,
+ ping the IPv4 server on the host side will fails.
+ When use "echo 0 > /sys/kernel/debug/tel/psd/data-pathv1/bypass_nat46" to enable the NAT46 translate,
+ ping the IPv4 server on the host side will success.
+
+----------------------------------------
+
+2, MIFI mode
+1) make kernel_menuconfig and select "DATA_PATH_NAT46" and save your new configuration.
+And then rebuild：make -j8 V=99
+
+2) Disable IPv6 in Ubuntu
+ "echo "net.ipv6.conf.all.disable_ipv6=1" >> /etc/sysctl.conf"
+ "sysctl -p"
+
+3) Redial using IPv6
+ "serial_client"
+ "AT+ZGDCONT=1,IPV6,GPRS"
+ "AT+ZGACT=1,1"
+ After this operation, you will not be able to access the IPv4 service and failed to ping IPv4 on the host or 1802s,
+ but you can successfully ping the IPv6 server on 1802s.
+
+4) NAT46 Configuration
+ Use "ifconfig" to query the IPv6 global address and local IPv4 address of ccinet,
+ you will get some information like this:
+ br-lan Link encap:Ethernet HWaddr 02:C0:84:B0:2A:99
+ inet addr:192.168.1.1 Bcast:192.168.1.255 Mask:255.255.255.0
+ inet6 addr: 240e:9a:8c9:f13d::1/64 Scope:Global
+ inet6 addr: fe80::c0:84ff:feb0:2a99/64 Scope:Link
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:29 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:55 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:0
+ RX bytes:3296 (3.2 KiB) TX bytes:6411 (6.2 KiB)
+
+ ccinet0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00
+ inet addr:10.164.56.133 Mask:255.255.255.255
+ inet6 addr: fe80::1/64 Scope:Link
+ inet6 addr: 240e:9a:8c9:f13d::1/64 Scope:Global
+ UP RUNNING NOARP MTU:1500 Metric:1
+ RX packets:28 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:35 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:2848 (2.7 KiB) TX bytes:3136 (3.0 KiB)
+
+ lo Link encap:Local Loopback
+ inet addr:127.0.0.1 Mask:255.0.0.0
+ inet6 addr: ::1/128 Scope:Host
+ UP LOOPBACK RUNNING MTU:65536 Metric:1
+ RX packets:142 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:142 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:0
+ RX bytes:7480 (7.3 KiB) TX bytes:7480 (7.3 KiB)
+
+ usbnet0 Link encap:Ethernet HWaddr 02:C0:84:B0:2A:99
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:34 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:66 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:3436 (3.3 KiB) TX bytes:12027 (11.7 KiB)
+
+ "10.164.56.133" will serve as the local IPv4 address in NAT46, and "240e:9a:8c9:f13d::1" will serve as the local IPv6 address in NAT46.
+ The detailed configuration is as follows:
+ "echo add nat46 | tee /sys/kernel/debug/tel/psd/data-pathv1/nat46_control"
+ "echo config nat46 local.v4 10.164.56.133/32 | tee /sys/kernel/debug/tel/psd/data-pathv1/nat46_control"
+ "echo config nat46 local.v6 240e:9a:8c9:f13d::1/64 | tee /sys/kernel/debug/tel/psd/data-pathv1/nat46_control"
+ "echo config nat46 local.style RFC6052 | tee /sys/kernel/debug/tel/psd/data-pathv1/nat46_control"
+ 32 indicates the mask length of the local IPv4 address, 64 indicates the prefix length of an IPv6 address.
+
+ if the remote IPv6 server is "240e:eb:8001:e05::/96",
+ "echo config nat46 remote.v6 240e:eb:8001:e05::/96 | tee /sys/kernel/debug/tel/psd/data-pathv1/nat46_control"
+ "echo config nat46 remote.style RFC6052 | tee /sys/kernel/debug/tel/psd/data-pathv1/nat46_control"
+
+ the command "echo 1 > /sys/kernel/debug/tel/psd/data-pathv1/bypass_nat46" can be used to terminate the NAT46 translate.
+
+5) Host Configuration
+ "dhclient enp0s26u1u1"
+ "route add default gw 192.168.1.1"
+
+6) Test
+ When we use "echo 1 > /sys/kernel/debug/tel/psd/data-pathv1/bypass_nat46" to terminate the NAT46 translate,
+ ping the IPv4 server on the host side will fails.
+ When we use "echo 0 > /sys/kernel/debug/tel/psd/data-pathv1/bypass_nat46" to enable the NAT46 translate,
+ ping the IPv4 server on the host side will success.
diff --git a/docs/marvell/howto/dual_apn.txt b/docs/marvell/howto/dual_apn.txt
new file mode 100644
index 0000000..161cb00
--- /dev/null
+++ b/docs/marvell/howto/dual_apn.txt
@@ -0,0 +1,92 @@
+How to create a dual APN and use the second APN to access the outer network
+========================================
+Here we take 1802s (i.e. NezhaS) as example, 1826 (i.e. Nezha3) is similar.
+
+1, Create a dual APN
+
+In the openwrt top dir,
+1) Modify the following contents in “target/Linux/MMP/asr1802s/config-3.10”
+ CONFIG_USB_ETH_RNDIS_ECM=y
+
+2) Modify the following contents in “target/linux/mmp/asr1802s/NEZAS201/base-files/etc/init.d/usb_init”
+ echo rndis,acm,marvell_diag,adb,ecm > /sys/class/android_usb/android0/functions
+ echo rndis,acm,marvell_diag,adb,ecm > /sys/class/android_usb/android0/win7
+ echo rndis,acm,marvell_diag,adb,ecm > /sys/class/android_usb/android0/win8
+ echo rndis,acm,marvell_diag,adb,ecm > /sys/class/android_usb/android0/olinux
+
+3) Modify the following contents in “package/network/config/firewall/Makefile”
+ DUAL_APN_FLAG=1
+
+4) Choose the profile config
+ make defconfig_asr1802sp201
+and build
+ make -j8 V=99
+
+5) Use SWDownloader to burn all bin files into the board
+
+6) Switch to pipe mode by AT command and reboot
+ AT+ACONFIG="PIPE=1"
+
+7) Use the AT command to dial-up Internet
+ AT+CGDCONT=2,"IP","cmwap"
+ AT+CGACT=1,2
+and query the IP of CMWAP
+ AT+CGDCONT?
+for example, you might get something like this:
++CGDCONT: 1,"IP","cmnet.mnc007.mcc460.gprs","10.36.148.238",0,0,,,,
+
++CGDCONT: 2,"IP","cmwap.mnc007.mcc460.gprs","100.74.21.147",0,0,0,2,0,0
+
+8) Configure the network
+ ifconfig ccinet1 100.74.21.147 netmask 255.255.255.0 up
+
+9) Test whether ccinet1 can ping the external network
+ ping -I ccinet1 8.8.8.8
+
+
+2, Access the external network through the lan
+
+1) Configure the Intranet network
+Connect the usb to your PC, You can see two new network adapters by "ifconfig" command,
+which corresponding to the virtual network cards usbnet0 and usbnet1 on 1802s. For example:
+
+ enp0s26u1u1 Link encap:Ethernet HWaddr 06:83:32:53:f7:0b
+ inet addr:10.36.148.238 Bcast:10.36.148.255 Mask:255.255.255.0
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:16 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:52 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:1823 (1.8 KB) TX bytes:8933 (8.9 KB)
+
+ enp0s26u1u1i6 Link encap:Ethernet HWaddr 26:b9:7a:b6:be:4a
+ UP BROADCAST MULTICAST MTU:1500 Metric:1
+ RX packets:0 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
+
+We need to configure the adapters enp0s26u1u1i6 and usbnet1 in the same small segment.
+OpenWrt:
+ ifconfig usbnet1 192.168.20.1 netmask 255.255.255.0 up
+Linux PC:
+ ifconfig enp0s26u1u1i6 192.168.20.100 netmask 255.255.255.0 up
+
+2) Configure the Router
+OpenWrt:
+ route add default gw 100.74.21.147 (the IP address of ccinet1)
+Linux PC:
+ route add default gw 192.168.20.1
+
+3) Configure the firewall
+Linux PC:
+ iptables -F
+ iptables -X
+ iptables -Z
+ iptables -A INPUT -j ACCEPT
+ iptables -A FORWARD -j ACCEPT
+ iptables -A OUTPUT -j ACCEPT
+
+4) Test whether enp0s26u1u1i6 can ping the external network
+Linux PC:
+ ping -I enp0s26u1u1i6 8.8.8.8
+
diff --git a/docs/marvell/howto/kagu-dual-pcie.txt b/docs/marvell/howto/kagu-dual-pcie.txt
new file mode 100644
index 0000000..f925860
--- /dev/null
+++ b/docs/marvell/howto/kagu-dual-pcie.txt
@@ -0,0 +1,22 @@
+How to use dual PCIe on ASR1826S(Kagu)
+========================================
+Dual PCIE wifi use RTL8812FR and RTL8192FR
+RTL8812FR and RTL8192FR share the same driver code. package/kernel/realtek-wl/rtl8192fr/src/rtl8192cd_driver/
+
+ASR1826s dual pcie use drivers/pci/host/pcie-kagu.c as pcie driver, and drivers/misc/pcie_dual_rfkill.c as pcie rfkill driver.
+And dual Pcie couldn't support suspend/resume. need to disable "echo mem > /sys/power/state"
+
+ASR1826s single PCIE share driver/pci/host/pcie-falcon.c with ASR1803/ASR1803E, and share drivers/misc/pcie8x_rfkill.c with ASR1803
+RTL8812FR and RTL8192FR only support wext mode.
+
+1. prepare kernel
+ copy marvell/linux/arch/arm/boot/dts/asr1826s-2pcie.dtsi to replease asr1826s.dtsi
+ copy asr1826s-p801-2pcie.dts to replease asr1826s-p801.dts
+2. prepare kernel config
+ copy target/linux/mmp/asr1826s/config-3.10-2pcie to replease target/linux/mmp/asr1826s/config-3.10
+
+3. menuconfig.
+ make defconfig_asr1826sp801_2pcie
+
+
+
diff --git a/docs/marvell/howto/repo_layout.png b/docs/marvell/howto/repo_layout.png
new file mode 100644
index 0000000..0efcffd
--- /dev/null
+++ b/docs/marvell/howto/repo_layout.png
Binary files differ
diff --git a/docs/marvell/howto/save_build_log.txt b/docs/marvell/howto/save_build_log.txt
new file mode 100644
index 0000000..bd542a1
--- /dev/null
+++ b/docs/marvell/howto/save_build_log.txt
@@ -0,0 +1,44 @@
+Logging Everything of make process
+
+The console's scrollback buffer will often prove to be too small to keep the full output of the package build process.
+
+There are moments you want to enable logging of the build process so that you can comfortably search(grep) through the logfiles
+when there appears to be a problem with building process
+
+The command looks like this:
+
+ make -j2 V=99 2>&1 | tee build.log
+
+0 is stdin. 1 is stdout. 2 is stderr
+
+There's one way to remember this construct (maybe it is not entirely accurate):
+ -------------
+ First of all, 2>1 looks like a very good way to redirect stderr to stdout. but remember,
+it has a very harmful disadvantage: it may actually be interpreted as "redirect stderr to a file named 1".
+ -------------
+ & indicates that what follows is a file descriptor and not a filename. So the construct becomes: 2>&1.
+ -------------
+ >& is shell syntax for "fold a file descriptor into another", you can also interprete it as
+"it is the syntax to redirect a stream to another file descriptor"
+
+The part " | tee build.log" causes a file build.log to be created (if it does not yet exist) and a copy of the text that
+your script displays on the console is going to be written to it.
+Any previous content of that logfile will be overwritten.
+
+The part "2>&1" means that you will also catch the ERROR output of failed commands. You would normally not notice,
+but programs can write their output to "standard output" as well as "error output".
+These are two separate "channels" if you like, and since the tee command will only catch "standard output" and
+duplicate it into the target file, you will have to explicitly add "error output" as well.
+Remember, the error output will often be the stuff you're most interested in!
+
+
+By using this command, you are still able to watch the proceedings of the package build process on your console,
+and afterwards you can open the log file in an editor at your leisure.
+
+look for the info:
+
+ •Compilation errors ( grep -iE "(error|failed)" )
+ •Header/include/library files missing ( grep -iE "(not found|unavailable)" )
+
+ref: http://tldp.org/LDP/abs/html/io-redirection.html
+
diff --git a/docs/marvell/howto/share_network_in_pipe_mode.txt b/docs/marvell/howto/share_network_in_pipe_mode.txt
new file mode 100644
index 0000000..b329c30
--- /dev/null
+++ b/docs/marvell/howto/share_network_in_pipe_mode.txt
@@ -0,0 +1,88 @@
+How to access the Internet inside the module in pipe mode
+========================================
+Problem Statement
+1826 PIPE mode works as follows: The IP address obtained by dial will be directly assigned to DAP.
+DAP sends the packet to 1826 via usb, the mrvlpipe driver intercepts and parses the IP header of
+the packet to determine whether to forward it to the slowpath or CCINETX and it also determine
+whether to forward to the slowpath or usb driver for downlink packets.
+Since there was no IP address configured for the local ccinetX, you cannot use the local ccinetX
+to send packets to the internet in 1826. For VoIP services, if the VoIP stack is placed inside 1826,
+the SIP packets cannot be sent to the sever.
+
+Share network in pipe mode is a technique meant to address this limitation. It will configures the
+IP address for the local CCINETX automatically and uses the tuple info to distinguish between internal
+and external access to the Internet.
+
+Notice:
+ 1) Before use this function, you need to understand a constraint that only certain items that are
+ accessed to the net internally can add their tuple information.
+ 2) Not support large packets, i.e. fragment packet, you need to control the packet length to be less
+ than MTU(default 1500).
+
+Here we take the VoIP as an example. Other services are similar.
+----------------------------------------------------------------------------
+Steps needed:
+1. make menuconfig, selects "Global build settings"->"Config support internal access to the internet in pipe mode"
+ and save to .config
+and build
+ make -j8 V=99
+
+2. Use SWDownloader to burn all bin files into the board
+
+3. Switch to pipe mode by AT command and reboot
+ AT+ACONFIG="PIPE=1"
+
+4. After reboot, you can see that there is also an IPv4 address on the local ccinetX, which is same with the IPv4
+address obtained by DAP. If you still need an IPv6 address, you can do that:
+ AT+CGDCONT=1,"IPV4V6","gprs"
+ AT+CGACT=1,1
+If dialed successful, you can see two IPv6 addresses on your local ccinetX, one is a link address and the other is
+a global address, looks like this:
+ ccinet0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00
+ inet addr:10.211.1.161 Mask:255.255.255.0
+ inet6 addr: fe80::1fb6:d1ac:88a1:e2c6/64 Scope:Link
+ inet6 addr: 2409:8930:2a3:1582:1fb6:d1ac:88a1:e2c6/64 Scope:Global
+ UP RUNNING NOARP MTU:1500 Metric:1
+
+5. Test
+ Before test whether the link from the local CCINETX to the SIP server is working, you need to add a tuple info
+to the "/sys/kernel/mpipe/database/tuple" to support ping the SIP server on 1826. For example,
+ echo 1 4 10.211.1.161 10.21.10.145 1 2048 1 > /sys/kernel/mpipe/database/tuple
+and then
+ ping 10.21.10.145 -I 10.211.1.161
+The usage for add the tuple info is as follows:
+echo [option] [version] [src_ip] [dst_ip] [sport] [dport] [protocol] > /sys/kernel/mpipe/database/tuple
+option:
+ 0------del all tuple info;
+ 1------add a specified tuple info;
+ 2------del a specified tuple info.
+
+6. In order to notify the mrvlpipe driver to forward the downlink packets locally, you need add the following sample
+code to the VoIP stack and get the IP version, source IP, destination IP, source port, destination port, protocol,
+and call this function before sends packets.
+
+ static int handle_tuple(TUPLE_CMD cmd, int version, char *src_ip,
+ char *dst_ip, int sport, int dport, int proto)
+ {
+ FILE *fp;
+ char write_buf[100] = {0};
+ int ret = 0;
+
+ fp = fopen("/sys/kernel/mpipe/database/tuple", "a+");
+ if(fp == NULL)
+ {
+ printf("handle_tuple: /sys/kernel/mpipe/database/tuple is not exit\n");
+ return -1;
+ }
+ snprintf(write_buf, sizeof(write_buf), "%u %u %s %s %u %u %u\r\n", cmd, version, src_ip, dst_ip, sport, dport, proto);
+ if(fwrite(write_buf, 1, strlen(write_buf), fp ) != strlen(write_buf))
+ {
+ printf("handle_tuple: file write error (size=%d)\n", strlen(write_buf));
+ ret = -1;
+ }
+
+ fclose(fp);
+
+ return ret;
+ }
+
diff --git a/docs/marvell/howto/start_and_build.txt b/docs/marvell/howto/start_and_build.txt
new file mode 100644
index 0000000..634206d
--- /dev/null
+++ b/docs/marvell/howto/start_and_build.txt
@@ -0,0 +1,125 @@
+0, Setup a workstation with 64-bit Linux OS installed (Ubuntu 14.04 and newer recommended)
+
+Make sure the workstation has the ssh key authorized by ASR.
+Make sure the ASR openwrt repositories are already cloned and updated
+
+Works below are all based on above two prerequisites.
+
+1, update the repos
+
+$ cd openwrt
+$ ./ugit.sh pull
+
+2, install the host prerequisites by openwrt
+
+$ apt-get install build-essential bison flex zlib1g-dev libncurses5-dev subversion quilt intltool ruby fastjar zip unzip gawk git-core
+
+3, update the feeds
+
+this is required at the first build, and the build after running 'make distclean'
+
+$ ./scripts/feeds update -a
+$ ./scripts/feeds install -a
+
+4, build the image
+
+First of first, let OpenWrt Buildroot check for missing packages on your build-system using
+
+$ make prereq
+
+Now, choose the proper defconfig files from the config directory according to the product profile.
+There are many profiles supported by default based on ASR DKB/EVB designs, i.e.
+ - pxa1826, for type A DKB, called nand profile in documents as well
+ - pxa1826spinand, for type A DKB with SPI flash, called spinand profile in documents as well
+ - pxa1826spinor, for data module, called spinor profile in documents as well
+ - pxa1826p601, for new designed EVB board, called p601 profile in documents as well
+
+Other profiles are not based on ASR DKB/EVB.
+
+Take pxa1826 nand profile for example,
+
+$make defconfig_pxa1826
+
+Then start the build
+$ make -j2 V=99
+
+After build finished, you can find the images at folder bin/pxa1826
+
+In the following development, just a simple build is enough if profile and config file are not changed.
+$ make -j2 V=99
+
+5, distclean uasge
+
+After the first build it will generate the toolchain and host tools, creating openwrt/host, openwrt/owtoolchain.
+In case you want to refresh those toolchains when some toolchain related configuration changed.
+
+$ make distclean
+$ ./scripts/feeds update -a
+$ ./scripts/feeds install -a
+$ make defconfig_pxa1826
+$ make -j2 V=99
+
+6, dirclean usage
+
+If you want to change the profile, for example, to pxa1826p601
+
+$make dirclean //make preclean is similar to dirclean but keeps the bin folder.
+$make defconfig_pxa1826p601
+$make -j2 V=99
+
+7, collect and check the build logs
+
+To save the build logs,
+
+$ make -j2 V=99 2>&1 | tee build.log
+
+To check error when build fails,
+
+$ make -j2 V=99 2>&1 | tee build.log | grep -i Error
+or
+$ grep -i Error build.log
+
+8, How to clean?
+
+- To clean the bin folder:
+ $ make clean
+
+- To clean the folders generated during build process:
+ $ make dirclean
+
+- To clean the folders generated during build process except the images:
+ $ make preclean
+
+- To clean everything, downloads, **configurations**, feeds,etc.
+ $ make distclean
+
+Only use distclean when necessary to save build time.
+
+9, How to build a specific package?
+
+It depends on where the package is located, following examples,
+
+ $ make package/obm-mmp/clean V=99
+ $ make package/obm-mmp/compile V=99
+ $ make package/obm-mmp/install V=99
+ or
+ $ make package/obm-mmp/{clean,compile,install} V=99
+
+ $ make package/feeds/packages/nginx/{clean, compile, install} V=99
+
+ $ make tools/automake/compile
+
+ $ make toolchain/{clean, compile, install}
+
+You can recompile only the kernel modules by issuing:
+
+ $ make target/linux/compile
+
+To recompile the static part of the kernel, issuing:
+
+ $ make target/linux/install
+
+Usually, you can do this for a complete kernel build,
+
+ $ make target/linux/{clean, compile, install}
+
diff --git a/docs/marvell/howto/update_defconfig.txt b/docs/marvell/howto/update_defconfig.txt
new file mode 100644
index 0000000..93b0d1d
--- /dev/null
+++ b/docs/marvell/howto/update_defconfig.txt
@@ -0,0 +1,25 @@
+How to update the defconfig for openwrt in the config direcotry
+
+In the openwrt top dir,
+
+1) need to choose the profile config, take defconfig_pxa1826 profile for example,
+$ make defconfig_pxa1826
+
+2) Above is Marvell defined defconfig per profile, it already set proper target and profile.
+Only if you want to add a new profile, need to change target or profile here
+$ make menuconfig //(it can be skipped in most times if not to change profile)
+(choose, save and exit)
+
+3) Next, only if want to update the kernel config in target/linux/mmp/pxa1826/,
+$ make kernel_menuconfig
+choose, save and exit
+
+4) Next again, when you want to update the openwrt settings or you have just updated the kernel config
+$ make menuconfig
+(choose), save and exit
+
+5) Last, save the new config file with configurations updated
+$ cp .config config/defconfig_pxa1826
+and build
+$ make -j2 V=99
+
diff --git a/docs/marvell/howto/use_vlan.txt b/docs/marvell/howto/use_vlan.txt
new file mode 100644
index 0000000..d4cb5af
--- /dev/null
+++ b/docs/marvell/howto/use_vlan.txt
@@ -0,0 +1,595 @@
+How to use VLAN to separate multiple PDN
+========================================
+Here we take 1802s (i.e. NezhaS) as example, 1826 (i.e. Nezha3) is similar.
+The host PC system tested in this paper is Ubuntu 5.4.0-6Ubuntu 1~16.04.12.
+Here we explains both the IPv4 and IPv6, you can ignore the IPv6 part if deploy the IPv4 only.
+
+1, PIPE mode
+1) Diag
+ default PDN:
+ "serial_client"
+ "AT+ZGDCONT=1,IPV4V6,CMNET"
+ "AT+ZGACT=1,1"
+ PDN2:
+ "AT*ZGDCONT=2,IPV4V6,CMWAP,1"
+ "AT+ZGACT=1,2"
+ PDN3:
+ "AT*ZGDCONT=3,IPV4V6,GPRS,1"
+ "AT+ZGACT=1,3"
+
+ Query the dial results with command "AT+CGDCONT?", you will get some information like this:
+
+ +CGDCONT: 1,"IPV4V6","cmnet","10.171.20.111 254.128.0.0.0.0.0.0.0.0.0.0.0.0.0.1",0,0,0,2,0,0
+
+ +CGDCONT: 2,"IPV4V6","CMWAP","10.184.75.11 254.128.0.0.0.0.0.0.0.0.0.0.0.0.0.1",0,0,0,2,0,0
+
+ +CGDCONT: 3,"IPV4V6","GPRS","10.185.130.179 254.128.0.0.0.0.0.0.0.0.0.0.0.0.0.1",0,0,0,2,0,0
+
+ As listed above , "10.171.20.111" is the IPv4 address of PDN1 and same for the others.
+
+2) Configure /etc/config/network
+ Add the following configuration to "/etc/config/network":
+
+ config switch
+ option name 'switch0'
+ option reset '1'
+ option enable_vlan '1'
+
+ config interface 'lan2'
+ option ifname 'usbnet0.100'
+ option type 'bridge'
+ option bridge_empty '1'
+ option proto 'static'
+ option ipaddr '10.184.75.244'
+ option netmask '255.255.255.0'
+ option ip6assign '60'
+
+ config interface 'lan3'
+ option ifname 'usbnet0.200'
+ option type 'bridge'
+ option bridge_empty '1'
+ option proto 'static'
+ option ipaddr '10.185.130.76'
+ option netmask '255.255.255.0'
+ option ip6assign '60'
+
+ usbnet0.100 and usbnet0.200 represent VLAN100 and VLAN200, "option ipaddr" is the ip address of PDN,
+ but the last bit requires an xor operation.
+ Then execute "/etc/init.d/network reload" to apply the configuration.
+
+3) Configure /etc/config/dhcp
+ Add the following configuration to "/etc/config/dhcp":
+
+ config dhcp 'lan2'
+ option interface 'lan2'
+ option leasetime '2h'
+ option dhcpv6 'server'
+ option ra 'relay'
+ option ndp 'relay'
+ option start '11'
+ option limit '0'
+ list dhcp_option '3,10.184.75.244'
+ list dhcp_option '1,255.255.255.0'
+ list dhcp_option '6,61.132.163.68,202.102.213.68'
+ list dns '240e:46:4088::4088'
+ list dns '240e:46:4888::4888'
+
+ config dhcp 'lan3'
+ option interface 'lan3'
+ option leasetime '2h'
+ option dhcpv6 'server'
+ option ra 'relay'
+ option ndp 'relay'
+ option start '179'
+ option limit '0'
+ list dhcp_option '3,10.185.130.76'
+ list dhcp_option '1,255.255.255.0'
+ list dhcp_option '6,202.102.213.68,61.132.163.68'
+ list dns '240e:46:4088::4088'
+ list dns '240e:46:4888::4888'
+
+ "option start" is the offset from the PDN address of the underlying interface to calculate the minimum address that may be leased to clients.
+ Then execute "/etc/init.d/dnsmasq reload" to apply the configuration.
+
+4) Bind the virtual LAN to PDN
+ Query the local IPv6 address for usbnet0:
+ "cd /sys/kernel/mpipe/devices"
+ "cat usbnet0/ll6addr", you will get the local IPv6 address:
+ "fe80::e8c9:89ff:fe4a:3455"
+
+ Configure virtual LAN:
+ "echo 192.168.100.1 > usbnet0.100/ipaddr"
+ "echo fe80::e8c9:89ff:fe4a:3455 > usbnet0.100/ll6addr"
+ "echo 1 > usbnet0.100/up"
+ "echo 1 > usbnet0.100/up6"
+
+ "echo 192.168.200.1 > usbnet0.200/ipaddr"
+ "echo fe80::e8c9:89ff:fe4a:3455 > usbnet0.200/ll6addr"
+ "echo 1 > usbnet0.200/up"
+ "echo 1 > usbnet0.200/up6"
+
+ Bind the virtual LAN to PDN
+ "echo usbnet0.100 > ccinet1/combineif"
+ "echo usbnet0.200 > ccinet2/combineif"
+ Now the ccinet1 serves as VLAN100, and ccinet2 as VLAN200.
+
+5) Configuration in Ubuntu16.04
+ Add virtual network card:
+ "vconfig add enp0s26u1u1 100"
+ "vconfig add enp0s26u1u1 200"
+
+ Get IP address through DHCP:
+ "dhcpcd enp0s26u1u1"
+ "dhcpcd enp0s26u1u1.100"
+ "dhcpcd enp0s26u1u1.200"
+
+ # ifconfig
+ enp0s26u1u1 Link encap:Ethernet HWaddr a2:ca:7e:71:c8:e3
+ inet addr:10.171.20.111 Bcast:10.171.20.255 Mask:255.255.255.0
+ inet6 addr: 240e:9a:875:27a8:9094:7d7b:6bc9:904a/64 Scope:Global
+ inet6 addr: 240e:9a:875:27a8:ae42:2167:938a:268/64 Scope:Global
+ inet6 addr: fe80::a0ca:7eff:fe71:c8e3/64 Scope:Link
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:709 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:574 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:69649 (69.6 KB) TX bytes:118056 (118.0 KB)
+
+ enp0s26u1u1.100 Link encap:Ethernet HWaddr a2:ca:7e:71:c8:e3
+ inet addr:10.184.75.11 Bcast:10.184.75.255 Mask:255.255.255.0
+ inet6 addr: 240e:9a:868:af6d:693a:c829:7dbe:c2d5/64 Scope:Global
+ inet6 addr: fe80::a0ca:7eff:fe71:c8e3/64 Scope:Link
+ inet6 addr: 240e:9a:868:af6d:fcf6:78f5:3ef3:d159/64 Scope:Global
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:9 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:123 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:1019 (1.0 KB) TX bytes:18273 (18.2 KB)
+
+ enp0s26u1u1.200 Link encap:Ethernet HWaddr a2:ca:7e:71:c8:e3
+ inet addr:10.185.130.179 Bcast:10.185.130.255 Mask:255.255.255.0
+ inet6 addr: fe80::52c1:fbe:ad29:61c9/64 Scope:Link
+ inet6 addr: 240e:9a:874:b759:61f5:109:a46c:fe33/64 Scope:Global
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:8 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:98 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:923 (923.0 B) TX bytes:13673 (13.6 KB)
+
+ Add the IPv4 routing:
+ "route add -net 1.1.1.0/24 dev enp0s26u1u1"
+ "route add -net 8.8.8.0/24 dev enp0s26u1u1.100"
+ "route add -net 114.114.114.0/24 dev enp0s26u1u1.200"
+
+6) Test in Ubuntu16.04
+ # ping 1.1.1.1
+ PING 1.1.1.1 (1.1.1.1) 56(84) bytes of data.
+ 64 bytes from 1.1.1.1: icmp_seq=1 ttl=53 time=257 ms
+ 64 bytes from 1.1.1.1: icmp_seq=2 ttl=53 time=171 ms
+
+ # ping 8.8.8.8
+ PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
+ 64 bytes from 8.8.8.8: icmp_seq=1 ttl=114 time=130 ms
+ 64 bytes from 8.8.8.8: icmp_seq=2 ttl=114 time=73.0 ms
+
+ # ping 114.114.114.114
+ PING 114.114.114.114 (114.114.114.114) 56(84) bytes of data.
+ 64 bytes from 114.114.114.114: icmp_seq=2 ttl=78 time=103 ms
+ 64 bytes from 114.114.114.114: icmp_seq=3 ttl=92 time=20.9 ms
+
+ # ping6 www.sohu.com -I enp0s26u1u1
+ PING www.sohu.com(2408:80f0:4100:4007::4) from 240e:9a:875:27a8:9094:7d7b:6bc9:904a enp0s26u1u1: 56 data bytes
+ 64 bytes from 2408:80f0:4100:4007::4: icmp_seq=1 ttl=53 time=47.6 ms
+ 64 bytes from 2408:80f0:4100:4007::4: icmp_seq=2 ttl=53 time=46.7 ms
+ 64 bytes from 2408:80f0:4100:4007::4: icmp_seq=3 ttl=53 time=49.8 ms
+
+ # ping6 www.sohu.com -I enp0s26u1u1.100
+ PING www.sohu.com(2408:80f0:4100:4007::4) from 240e:9a:868:af6d:693a:c829:7dbe:c2d5 enp0s26u1u1.100: 56 data bytes
+ 64 bytes from 2408:80f0:4100:4007::4: icmp_seq=1 ttl=53 time=72.3 ms
+ 64 bytes from 2408:80f0:4100:4007::4: icmp_seq=2 ttl=53 time=63.8 ms
+ 64 bytes from 2408:80f0:4100:4007::4: icmp_seq=3 ttl=53 time=50.8 ms
+
+ # ping6 www.sohu.com -I enp0s26u1u1.200
+ PING www.sohu.com(2408:80f0:4100:4007::5) from 240e:9a:874:b759:61f5:109:a46c:fe33 enp0s26u1u1.200: 56 data bytes
+ 64 bytes from 2408:80f0:4100:4007::5: icmp_seq=1 ttl=53 time=73.7 ms
+ 64 bytes from 2408:80f0:4100:4007::5: icmp_seq=2 ttl=53 time=54.8 ms
+ 64 bytes from 2408:80f0:4100:4007::5: icmp_seq=3 ttl=53 time=45.6 ms
+
+7) VLAN for the default PDN
+ Since the default PDN is bound to the br-lan, you need to re-bind it to the desired VLAN and re-specify the br-lan address.
+ For example, bind to the VLAN 10:
+ First, modify the /etc/config/network configure file:
+
+ config interface 'lan'
+ option ifname 'usbnet0 hsicnet0 eth0'
+ option type 'bridge'
+ option bridge_empty '1'
+ option proto 'static'
+ option ip6assign '60'
+ option netmask '255.255.255.0'
+ list ipaddr '192.168.1.1'
+
+ config switch
+ option name 'switch0'
+ option reset '1'
+ option enable_vlan '1'
+
+ config interface 'lan1'
+ option ifname 'usbnet0.10'
+ option type 'bridge'
+ option bridge_empty '1'
+ option proto 'static'
+ option ipaddr '10.171.20.144'
+ option netmask '255.255.255.0'
+ option ip6assign '60'
+
+ Second, modify the /etc/config/dhcp configure file, then execute "/etc/init.d/network reload" to apply the configuration:
+ config dhcp 'lan'
+ option interface 'lan'
+ option start '100'
+ option limit '150'
+ option leasetime '2h'
+ option dhcpv6 'server'
+ option ra 'relay'
+ option ndp 'relay'
+
+ config dhcp 'lan1'
+ option interface 'lan1'
+ option leasetime '2h'
+ option dhcpv6 'server'
+ option ra 'relay'
+ option ndp 'relay'
+ option start '111'
+ option limit '0'
+ list dhcp_option '3,10.171.20.144'
+ list dhcp_option '1,255.255.255.0'
+ list dhcp_option '6,202.102.213.68,61.132.163.68'
+ list dns '240e:46:4088::4088'
+ list dns '240e:46:4888::4888'
+
+ Last, bind the virtual LAN to the default PDN:
+ "echo 192.168.10.1 > /sys/kernel/mpipe/devices/usbnet0.10/ipaddr"
+ "echo fe80::e8c9:89ff:fe4a:3455 > /sys/kernel/mpipe/devices/usbnet0.10/ll6addr"
+ "echo 1 > /sys/kernel/mpipe/devices/usbnet0.10/up"
+ "echo 1 > /sys/kernel/mpipe/devices/usbnet0.10/up6"
+ "echo usbnet0.10 > /sys/kernel/mpipe/devices/ccinet0/combineif"
+
+ The routing configuration in ubuntu is similar to the above step (5).
+
+8) Note
+ If you disconnect the usb, you may need to follow the above steps to reconfigure after reconnect.
+ If the default PDN is also bound to the VLAN, the ubutun PC can only access the internet via the virtual VLAN network card, while the enumerated real network card will not be able to access the internet.
+
+----------------------------------------
+
+2, MIFI mode
+1) Diag
+ default PDN:
+ "serial_client"
+ "AT+ZGDCONT=1,IPV4V6,CMNET"
+ "AT+ZGACT=1,1"
+ PDN2:
+ "AT*ZGDCONT=2,IPV4V6,CMWAP,1"
+ "AT+ZGACT=1,2"
+ PDN3:
+ "AT*ZGDCONT=3,IPV4V6,GPRS,1"
+ "AT+ZGACT=1,3"
+ Query the dial results with command "AT+CGDCONT?", you will get some information like this:
+
+ +CGDCONT: 1,"IP","ctnet.mnc011.mcc460.gprs","10.159.180.217",0,0,,,,
+
+ +CGDCONT: 2,"IP","cmwap","10.156.82.62",0,0,0,2,0,0
+
+ +CGDCONT: 3,"IP","cmwap","10.146.8.82",0,0,0,2,0,0
+
+ As listed above , "10.159.180.217" is the IPv4 address of PDN1 and same for the others.
+
+ Modify the route configuration, such as:
+ "route add -net 114.114.114.0/24 gw 10.146.8.82"
+ "route add -net 8.8.8.0/24 gw 10.156.82.62"
+ "route add -net 1.1.1.0/24 gw 10.159.180.217"
+
+ # route
+ Kernel IP routing table
+ Destination Gateway Genmask Flags Metric Ref Use Iface
+ 1.1.1.0 10.159.180.217 255.255.255.0 UG 0 0 0 ccinet0
+ 8.8.8.0 10.156.82.62 255.255.255.0 UG 0 0 0 ccinet1
+ 114.114.114.0 10.146.8.82 255.255.255.0 UG 0 0 0 ccinet2
+ 192.168.1.0 * 255.255.255.0 U 0 0 0 br-lan
+ 192.168.100.0 * 255.255.255.0 U 0 0 0 br-lan2
+ 192.168.200.0 * 255.255.255.0 U 0 0 0 br-lan3
+
+2) Configure /etc/config/network
+ Add the following configuration to "/etc/config/network":
+
+ config switch
+ option name 'switch0'
+ option reset '1'
+ option enable_vlan '1'
+
+ config interface 'lan2'
+ option ifname 'usbnet0.100'
+ option type 'bridge'
+ option bridge_empty '1'
+ option proto 'static'
+ option ipaddr '192.168.100.1'
+ option netmask '255.255.255.0'
+ option ip6assign '60'
+
+ config interface 'lan3'
+ option ifname 'usbnet0.200'
+ option type 'bridge'
+ option bridge_empty '1'
+ option proto 'static'
+ option ipaddr '192.168.200.1'
+ option netmask '255.255.255.0'
+ option ip6assign '60'
+
+ usbnet0.100 and usbnet0.200 represent VLAN100 and VLAN200.
+ Then execute "/etc/init.d/network reload" to apply the configuration.
+
+3) Modify /etc/config/firewall
+ The forwarding rules are set as follows:
+
+ config zone
+ option name lan
+ list network 'lan'
+ option input ACCEPT
+ option output ACCEPT
+ option forward ACCEPT
+
+ config zone
+ option name wan
+ list network 'wan0'
+ list network 'wan3'
+ list network 'wan4'
+ list network 'wan5'
+ list network 'wan6'
+ list network 'wan7'
+ list network 'wan60'
+ list network 'wan63'
+ list network 'wan64'
+ list network 'wan65'
+ list network 'wan66'
+ list network 'wan67'
+ list network 'wlan'
+ list network 'wlan6'
+ option input REJECT
+ option output ACCEPT
+ option forward REJECT
+ option masq 1
+ option mtu_fix 1
+
+ config forwarding
+ option src lan
+ option dest wan
+
+ config zone
+ option name lan2
+ list network 'lan2'
+ option input ACCEPT
+ option output ACCEPT
+ option forward ACCEPT
+
+ config zone
+ option name wan_100
+ list network 'wan1'
+ list network 'wan61'
+ option input REJECT
+ option output ACCEPT
+ option forward REJECT
+ option masq 1
+ option mtu_fix 1
+
+ config forwarding
+ option src lan2
+ option dest wan_100
+
+ config zone
+ option name lan3
+ list network 'lan3'
+ option input ACCEPT
+ option output ACCEPT
+ option forward ACCEPT
+
+ config zone
+ option name wan_200
+ list network 'wan2'
+ list network 'wan62'
+ option input REJECT
+ option output ACCEPT
+ option forward REJECT
+ option masq 1
+ option mtu_fix 1
+
+ config forwarding
+ option src lan3
+ option dest wan_200
+
+ Then execute "/etc/init.d/firewall reload" to apply the configuration.
+
+4) Configure /etc/config/dhcp
+ Add the following configuration to "/etc/config/dhcp":
+
+ config dhcp 'lan2'
+ option interface 'lan2'
+ option start '100'
+ option limit '150'
+ option leasetime '2h'
+ option dhcpv6 'server'
+ option ra 'relay'
+ option ndp 'relay'
+
+ config dhcp 'lan3'
+ option interface 'lan3'
+ option start '100'
+ option limit '150'
+ option leasetime '2h'
+ option dhcpv6 'server'
+ option ra 'relay'
+ option ndp 'relay'
+
+ Then execute "/etc/init.d/dnsmasq reload" to apply the configuration.
+
+5) Configuration in Ubuntu16.04
+ Add virtual network card:
+ "vconfig add enp0s26u1u1 100"
+ "vconfig add enp0s26u1u1 200"
+
+ Get IP address through DHCP:
+ "dhcpcd enp0s26u1u1"
+ "dhcpcd enp0s26u1u1.100"
+ "dhcpcd enp0s26u1u1.200"
+
+ # ifconfig
+ enp0s26u1u1 Link encap:Ethernet HWaddr 02:29:f2:b7:fa:81
+ inet addr:192.168.1.134 Bcast:192.168.1.255 Mask:255.255.255.0
+ inet6 addr: 240e:9a:428:44c9:acae:1690:47d3:710c/64 Scope:Global
+ inet6 addr: 240e:9a:428:44c9:29:f2ff:feb7:fa81/64 Scope:Global
+ inet6 addr: fe80::29:f2ff:feb7:fa81/64 Scope:Link
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:13141 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:2393 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:1284895 (1.2 MB) TX bytes:570332 (570.3 KB)
+
+ enp0s26u1u1.100 Link encap:Ethernet HWaddr 02:29:f2:b7:fa:81
+ inet addr:192.168.100.203 Bcast:192.168.100.255 Mask:255.255.255.0
+ inet6 addr: 240e:9a:417:66b8:29:f2ff:feb7:fa81/64 Scope:Global
+ inet6 addr: 240e:9a:428:44c9:f6e7:c272:3fba:6a7d/64 Scope:Global
+ inet6 addr: fe80::29:f2ff:feb7:fa81/64 Scope:Link
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:3969 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:898 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:398354 (398.3 KB) TX bytes:131123 (131.1 KB)
+
+ enp0s26u1u1.200 Link encap:Ethernet HWaddr 02:29:f2:b7:fa:81
+ inet addr:192.168.200.203 Bcast:192.168.200.255 Mask:255.255.255.0
+ inet6 addr: 240e:9a:419:2597:29:f2ff:feb7:fa81/64 Scope:Global
+ inet6 addr: 240e:9a:419:2597:6433:4697:bff4:45c9/64 Scope:Global
+ inet6 addr: 240e:9a:428:44c9:29:f2ff:feb7:fa81/64 Scope:Global
+ inet6 addr: fe80::29:f2ff:feb7:fa81/64 Scope:Link
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:3898 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:629 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:404558 (404.5 KB) TX bytes:118583 (118.5 KB)
+
+ Add the IPv4 routing:
+ "route add -net 1.1.1.0/24 gw 192.168.1.1"
+ "route add -net 8.8.8.0/24 gw 192.168.100.1"
+ "route add -net 114.114.114.0/24 gw 192.168.200.1"
+
+ # route
+ Kernel IP routing table
+ Destination Gateway Genmask Flags Metric Ref Use Iface
+ 1.1.1.0 192.168.1.1 255.255.255.0 UG 0 0 0 enp0s26u1u1
+ 8.8.8.0 192.168.100.1 255.255.255.0 UG 0 0 0 enp0s26u1u1.100
+ 114.114.114.0 192.168.200.1 255.255.255.0 UG 0 0 0 enp0s26u1u1.200
+ 192.168.1.0 * 255.255.255.0 U 0 0 0 enp0s26u1u1
+ 192.168.100.0 * 255.255.255.0 U 0 0 0 enp0s26u1u1.100
+ 192.168.200.0 * 255.255.255.0 U 0 0 0 enp0s26u1u1.200
+
+6) Test in Ubuntu16.04
+ # ping 1.1.1.1
+ PING 1.1.1.1 (1.1.1.1) 56(84) bytes of data.
+ 64 bytes from 1.1.1.1: icmp_seq=1 ttl=52 time=223 ms
+ 64 bytes from 1.1.1.1: icmp_seq=2 ttl=52 time=173 ms
+ 64 bytes from 1.1.1.1: icmp_seq=3 ttl=52 time=169 ms
+
+ # ping 8.8.8.8
+ PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
+ 64 bytes from 8.8.8.8: icmp_seq=2 ttl=113 time=54.7 ms
+ 64 bytes from 8.8.8.8: icmp_seq=3 ttl=113 time=52.3 ms
+ 64 bytes from 8.8.8.8: icmp_seq=4 ttl=113 time=53.0 ms
+
+ # ping 114.114.114.114
+ PING 114.114.114.114 (114.114.114.114) 56(84) bytes of data.
+ 64 bytes from 114.114.114.114: icmp_seq=1 ttl=65 time=201 ms
+ 64 bytes from 114.114.114.114: icmp_seq=2 ttl=86 time=25.0 ms
+ 64 bytes from 114.114.114.114: icmp_seq=3 ttl=90 time=25.0 ms
+
+ # ping6 240e:83:201:3700::4 -I enp0s26u1u1
+ PING 240e:83:201:3700::4(240e:83:201:3700::4) from 240e:9a:428:44c9:acae:1690:47d3:710c enp0s26u1u1: 56 data bytes
+ 64 bytes from 240e:83:201:3700::4: icmp_seq=1 ttl=57 time=45.2 ms
+ 64 bytes from 240e:83:201:3700::4: icmp_seq=2 ttl=57 time=32.8 ms
+ 64 bytes from 240e:83:201:3700::4: icmp_seq=3 ttl=57 time=32.0 ms
+ 64 bytes from 240e:83:201:3700::4: icmp_seq=4 ttl=57 time=31.2 ms
+
+ # ping6 240e:83:201:3700::4 -I enp0s26u1u1.100
+ PING 240e:83:201:3700::4(240e:83:201:3700::4) from 240e:9a:417:66b8:29:f2ff:feb7:fa81 enp0s26u1u1.100: 56 data bytes
+ 64 bytes from 240e:83:201:3700::4: icmp_seq=1 ttl=57 time=42.0 ms
+ 64 bytes from 240e:83:201:3700::4: icmp_seq=2 ttl=57 time=33.8 ms
+ 64 bytes from 240e:83:201:3700::4: icmp_seq=3 ttl=57 time=33.8 ms
+ 64 bytes from 240e:83:201:3700::4: icmp_seq=4 ttl=57 time=30.7 ms
+
+ # ping6 240e:83:201:3700::4 -I enp0s26u1u1.200
+ PING 240e:83:201:3700::4(240e:83:201:3700::4) from 240e:9a:419:2597:6433:4697:bff4:45c9 enp0s26u1u1.200: 56 data bytes
+ 64 bytes from 240e:83:201:3700::4: icmp_seq=1 ttl=57 time=31.9 ms
+ 64 bytes from 240e:83:201:3700::4: icmp_seq=2 ttl=57 time=33.0 ms
+ 64 bytes from 240e:83:201:3700::4: icmp_seq=3 ttl=57 time=35.1 ms
+ 64 bytes from 240e:83:201:3700::4: icmp_seq=4 ttl=57 time=33.7 ms
+
+7) VLAN for the default PDN
+ In MIFI mode, you just need to modify the /etc/config/firewall configure file.
+ For example, bind to the VLAN 10:
+ Modify the /etc/config/firewall configure file, then execute "/etc/init.d/firewall reload" to apply the configuration.:
+
+ config zone
+ option name lan
+ list network 'lan'
+ option input ACCEPT
+ option output ACCEPT
+ option forward ACCEPT
+
+ config zone
+ option name wan
+ list network 'wan3'
+ list network 'wan4'
+ list network 'wan5'
+ list network 'wan6'
+ list network 'wan7'
+ list network 'wan63'
+ list network 'wan64'
+ list network 'wan65'
+ list network 'wan66'
+ list network 'wan67'
+ list network 'wlan'
+ list network 'wlan6'
+ option input REJECT
+ option output ACCEPT
+ option forward REJECT
+ option masq 1
+ option mtu_fix 1
+
+ config forwarding
+ option src lan
+ option dest wan
+
+ config zone
+ option name lan1
+ list network 'lan1'
+ option input ACCEPT
+ option output ACCEPT
+ option forward ACCEPT
+
+ config zone
+ option name wan_10
+ list network 'wan0'
+ list network 'wan60'
+ option input REJECT
+ option output ACCEPT
+ option forward REJECT
+ option masq 1
+ option mtu_fix 1
+
+ config forwarding
+ option src lan1
+ option dest wan_10
+
+ The routing configuration in ubuntu is similar to the above step (5) and module is similar to the above step (1).
+
+8) Note
+ If you disconnect the usb, you may need to follow the above steps to reconfigure after reconnect.
+ If the default PDN is also bound to the VLAN, the ubutun PC can only access the internet via the virtual VLAN network card, while the enumerated real network card will not be able to access the internet.
diff --git a/docs/marvell/howto/use_vlan_base_eth.txt b/docs/marvell/howto/use_vlan_base_eth.txt
new file mode 100644
index 0000000..fdae5d4
--- /dev/null
+++ b/docs/marvell/howto/use_vlan_base_eth.txt
@@ -0,0 +1,255 @@
+How to use VLAN base on ETH to separate multiple PDN
+========================================
+Here we take 1803 as example, the host PC system tested in this paper is Ubuntu 5.4.0-6Ubuntu 1~16.04.12.
+Here we explains both the IPv4 and IPv6, you can ignore the IPv6 part if deploy the IPv4 only.
+
+1, PIPE mode
+1) Diag
+ default PDN:
+ "serial_client"
+ AT+ZGDCONT=1,IPV4V6,CMNET
+ AT+ZGACT=1,1
+ PDN2:
+ AT*ZGDCONT=2,IPV4V6,CMWAP,1
+ AT+ZGACT=1,2
+ PDN3:
+ AT*ZGDCONT=3,IPV4V6,GPRS,1
+ AT+ZGACT=1,3
+
+ Query the dial results with command "AT+CGCONTRDP", you will get some information like this:
+
+ +CGCONTRDP: 1,5,"cmnet.mnc002.mcc460.gprs","10.83.56.210","","211.138.180.2","211.138.180.3","","",0,0
+
+ +CGCONTRDP: 1,5,"cmnet.mnc002.mcc460.gprs","254.128.0.0.0.0.0.0.64.146.26.57.99.145.79.134","","36.9.128.48.32.0.0.0.0.0.0.0.0.0.0.1","36.9.128.48.32.0.0.0.0.0.0.0.0.0.0.2","","",0,0
+
+ +CGCONTRDP: 2,6,"cmnet.mnc002.mcc460.gprs","10.83.152.65","","211.138.180.2","211.138.180.3","","",0,0
+
+ +CGCONTRDP: 2,6,"cmnet.mnc002.mcc460.gprs","254.128.0.0.0.0.0.0.147.189.59.114.229.84.73.203","","36.9.128.48.32.0.0.0.0.0.0.0.0.0.0.1","36.9.128.48.32.0.0.0.0.0.0.0.0.0.0.2","","",0,0
+
+ +CGCONTRDP: 3,7,"cmnet.mnc002.mcc460.gprs","10.83.223.9","","211.138.180.2","211.138.180.3","","",0,0
+
+ +CGCONTRDP: 3,7,"cmnet.mnc002.mcc460.gprs","254.128.0.0.0.0.0.0.119.145.137.164.221.238.176.216","","36.9.128.48.32.0.0.0.0.0.0.0.0.0.0.1","36.9.128.48.32.0.0.0.0.0.0.0.0.0.0.2","","",0,0
+
+ As listed above , "10.83.56.210" is the IPv4 address of PDN1 and same for the others.
+
+2) Configure /etc/config/network
+ Add the following configuration to "/etc/config/network":
+ LAN4 is used to login to WebUI or connect module with fixed IP addresses.
+
+ config switch
+ option name 'switch0'
+ option reset '1'
+ option enable_vlan '1'
+
+ config interface 'lan2'
+ option ifname 'eth0.100'
+ option type 'bridge'
+ option bridge_empty '1'
+ option proto 'static'
+ option ipaddr '10.83.152.190'
+ option netmask '255.255.255.0'
+ option ip6assign '60'
+
+ config interface 'lan3'
+ option ifname 'eth0.200'
+ option type 'bridge'
+ option bridge_empty '1'
+ option proto 'static'
+ option ipaddr '10.83.223.246'
+ option netmask '255.255.255.0'
+ option ip6assign '60'
+
+ config interface 'lan4'
+ option ifname 'eth0.300'
+ option type 'bridge'
+ option bridge_empty '1'
+ option proto 'static'
+ option ipaddr '192.168.1.1'
+ option netmask '255.255.255.0'
+ option ip6assign '60'
+
+ eth0.100 and eth0.200 represent VLAN100 and VLAN200, "option ipaddr" is the ip address of PDN,
+ but the last bit requires an xor operation.
+ Then execute "/etc/init.d/network reload" to apply the configuration.
+
+3) Configure /etc/config/dhcp
+ Add the following configuration to "/etc/config/dhcp":
+
+ config dhcp 'lan2'
+ option interface 'lan2'
+ option leasetime '2h'
+ option dhcpv6 'server'
+ option ra 'relay'
+ option ndp 'relay'
+ option start '65'
+ option limit '0'
+ list dhcp_option '3,10.83.152.190'
+ list dhcp_option '1,255.255.255.0'
+ list dhcp_option '6,211.138.180.3,211.138.180.2'
+ list dns '2409:8030:2000::1'
+ list dns '2409:8030:2000::2'
+
+ config dhcp 'lan3'
+ option interface 'lan3'
+ option leasetime '2h'
+ option dhcpv6 'server'
+ option ra 'relay'
+ option ndp 'relay'
+ option start '9'
+ option limit '0'
+ list dhcp_option '3,10.83.223.246'
+ list dhcp_option '1,255.255.255.0'
+ list dhcp_option '6,211.138.180.3,211.138.180.2'
+ list dns '2409:8030:2000::1'
+ list dns '2409:8030:2000::2'
+
+ config dhcp 'lan4'
+ option interface 'lan4'
+ option start '192.168.1.100'
+ option end '192.168.1.249'
+ option limit '150'
+ option leasetime '43200'
+ option dhcpv6 'server'
+ option ra 'relay'
+ option ndp 'relay'
+
+ "option start" is the offset from the PDN address of the underlying interface to calculate the minimum address that may be leased to clients.
+ Then execute "/etc/init.d/dnsmasq reload" to apply the configuration.
+
+4) Bind the virtual LAN to PDN
+ Query the local IPv6 address for eth0:
+ Query the local IPv6 address for eth0:
+ ifconfig br-lan(*) | grep "inet6 addr" | awk '{print $3}'
+ For example, you will get the local IPv6 address for br-lan,
+ "fe80::30e1:7fff:febc:a4e1/64"
+
+ Configure virtual LAN:
+ "echo 192.168.0.1 > eth0/ipaddr"
+ "echo fe80::30e1:7fff:febc:a4e1 > eth0/ll6addr"
+ "echo 1 > eth0/up"
+ "echo 1 > eth0/up6"
+
+ "echo 192.168.100.1 > eth0.100/ipaddr"
+ "echo <br-lan2 local ipv6 addr> > eth0.100/ll6addr"
+ "echo 1 > eth0.100/up"
+ "echo 1 > eth0.100/up6"
+
+ "echo 192.168.200.1 > eth0.200/ipaddr"
+ "echo <br-lan3 local ipv6 addr> > eth0.200/ll6addr"
+ "echo 1 > eth0.200/up"
+ "echo 1 > eth0.200/up6"
+
+ "echo 192.168.1.1 > eth0.300/ipaddr"
+ "echo 1 > eth0.300/up"
+
+ Bind the virtual LAN to PDN
+ "echo eth0 > ccinet0/combineif"
+ "echo eth0.100 > ccinet1/combineif"
+ "echo eth0.200 > ccinet2/combineif"
+ Now the ccinet1 serves as VLAN100 and ccinet2 as VLAN200, ccinet0 has no vlan.
+
+5) Configuration in Ubuntu16.04
+ Add virtual network card:
+ "vconfig add eno1 100"
+ "vconfig add eno1 200"
+ "vconfig add eno1 300"
+
+ Get IP address through DHCP:
+ "dhcpcd eno1"
+ "dhcpcd eno1.100"
+ "dhcpcd eno1.200"
+ "dhcpcd eno1.200 -4"
+
+ # ifconfig
+ eno1 Link encap:Ethernet HWaddr fc:4d:d4:47:76:7c
+ inet addr:10.83.56.210 Bcast:10.83.56.255 Mask:255.255.255.0
+ inet6 addr: 2409:8930:265:340e:eaad:ceec:7eee:30ca/64 Scope:Global
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:8382 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:7057 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:2229048 (2.2 MB) TX bytes:941209 (941.2 KB)
+ Interrupt:20 Memory:f7c00000-f7c20000
+
+ eno1.100 Link encap:Ethernet HWaddr fc:4d:d4:47:76:7c
+ inet addr:10.83.152.65 Bcast:10.83.152.255 Mask:255.255.255.0
+ inet6 addr: 2409:8930:265:3582:9561:16:150:31fc/64 Scope:Global
+ inet6 addr: 2409:8930:265:3582:884b:4cd7:ec22:1a8a/64 Scope:Global
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:321 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:982 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:42395 (42.3 KB) TX bytes:136625 (136.6 KB)
+
+ eno1.200 Link encap:Ethernet HWaddr fc:4d:d4:47:76:7c
+ inet addr:10.83.223.9 Bcast:10.83.223.255 Mask:255.255.255.0
+ inet6 addr: 2409:8930:265:372a:3d07:6ef3:72e1:fb32/64 Scope:Global
+ inet6 addr: fe80::9e83:97a5:fce9:f67b/64 Scope:Link
+ inet6 addr: 2409:8930:265:372a:e040:801d:d009:6860/64 Scope:Global
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:291 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:662 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:37415 (37.4 KB) TX bytes:94854 (94.8 KB)
+
+ eno1.300 Link encap:Ethernet HWaddr fc:4d:d4:47:76:7c
+ inet addr:192.168.1.244 Bcast:192.168.1.255 Mask:255.255.255.0
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:2336 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:2453 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:277235 (277.2 KB) TX bytes:313953 (313.9 KB)
+
+ # route
+ Kernel IP routing table
+ Destination Gateway Genmask Flags Metric Ref Use Iface
+ default 10.83.56.45 0.0.0.0 UG 202 0 0 eno1
+ default 10.83.152.190 0.0.0.0 UG 203 0 0 eno1.100
+ default 10.83.223.246 0.0.0.0 UG 204 0 0 eno1.200
+ default 192.168.1.1 0.0.0.0 UG 205 0 0 eno1.300
+ 10.83.56.0 * 255.255.255.0 U 202 0 0 eno1
+ 10.83.152.0 * 255.255.255.0 U 203 0 0 eno1.100
+ 10.83.223.0 * 255.255.255.0 U 204 0 0 eno1.200
+ 192.168.1.0 * 255.255.255.0 U 205 0 0 eno1.300
+
+6) Test in Ubuntu16.04
+
+ # ping www.sohu.com -I eno1
+ PING fshyd.a.sohu.com (162.14.132.217) from 10.83.56.210 eno1: 56(84) bytes of data.
+ 64 bytes from 162.14.132.217: icmp_seq=1 ttl=247 time=44.4 ms
+ 64 bytes from 162.14.132.217: icmp_seq=2 ttl=247 time=44.9 ms
+
+ # route del default gw 10.83.56.45
+ # ping www.sohu.com -I eno1.100
+ PING fshyd.a.sohu.com (162.14.132.217) from 10.83.152.65 eno1.100: 56(84) bytes of data.
+ 64 bytes from 162.14.132.217: icmp_seq=1 ttl=247 time=29.4 ms
+ 64 bytes from 162.14.132.217: icmp_seq=2 ttl=247 time=27.1 ms
+
+ # route del default gw 10.83.152.190
+ # ping www.sohu.com -I eno1.200
+ PING fshyd.a.sohu.com (162.14.132.217) from 10.83.223.9 eno1.200: 56(84) bytes of data.
+ 64 bytes from 162.14.132.217: icmp_seq=1 ttl=54 time=54.6 ms
+ 64 bytes from 162.14.132.217: icmp_seq=2 ttl=54 time=43.0 ms
+
+ # ping 192.168.1.1
+ PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data.
+ 64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.93 ms
+ 64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.11 ms
+
+ # ping6 www.sohu.com -I eno1
+ PING www.sohu.com(2402:4e00:4010:1::20) from 2409:8930:265:340e:eaad:ceec:7eee:30ca eno1: 56 data bytes
+ 64 bytes from 2402:4e00:4010:1::20: icmp_seq=2 ttl=50 time=63.9 ms
+ 64 bytes from 2402:4e00:4010:1::20: icmp_seq=3 ttl=50 time=42.7 ms
+
+ # ping6 www.sohu.com -I eno1.100
+ PING www.sohu.com(2402:4e00:4010:1::21) from 2409:8930:265:3582:9561:16:150:31fc eno1.100: 56 data bytes
+ 64 bytes from 2402:4e00:4010:1::21: icmp_seq=1 ttl=50 time=29.7 ms
+ 64 bytes from 2402:4e00:4010:1::21: icmp_seq=2 ttl=50 time=38.3 ms
+
+ # ping6 www.sohu.com -I eno1.200
+ PING www.sohu.com(2402:4e00:4010:1::25) from 2409:8930:265:372a:e040:801d:d009:6860 eno1.200: 56 data bytes
+ 64 bytes from 2402:4e00:4010:1::25: icmp_seq=1 ttl=50 time=52.9 ms
+ 64 bytes from 2402:4e00:4010:1::25: icmp_seq=2 ttl=50 time=47.1 ms
+
+7) Note
+ If you disconnect the eth, you may need to follow the above steps to reconfigure after reconnect.
diff --git a/docs/marvell/howto/vpn_configuration.txt b/docs/marvell/howto/vpn_configuration.txt
new file mode 100644
index 0000000..1a849a6
--- /dev/null
+++ b/docs/marvell/howto/vpn_configuration.txt
@@ -0,0 +1,82 @@
+How to configure VPN
+========================================
+Here we provide some example of the tunneling protocol configurations usable in /etc/config/network.
+We will also provide the opkg packages that need to be installed for protocol support below.
+
+1, GRE
+The PACKAGE_gre must be installed to use this protocol. Additionally, you need PACKAGE_grev4 and/or PACKAGE_grev6.
+example for create a GRE tunnel:
+
+ # /etc/config/network
+ config interface 'vpn'
+ option proto 'gre'
+ option peeraddr 'peeraddr'
+
+ config interface 'gre_tunnel'
+ option ifname '@vpn'
+ option proto 'static'
+ option netmask 'netmask'
+ option ipaddr 'ipaddress'
+ #If you need to configure IPv6.
+ option ip6addr 'ipaddress'
+
+2, PPTP
+The following packages must be installed to use this protocol.
+ PACKAGE_kmod-nf-nathelper-extra
+ PACKAGE_kmod-gre
+ PACKAGE_kmod-pptp
+ PACKAGE_ppp
+ PACKAGE_kmod-ppp
+ PACKAGE_ppp-mod-pptp
+
+example for create PPTP:
+ # /etc/config/network
+ config interface 'vpn'
+ option ifname 'pptp-vpn'
+ option proto 'pptp'
+ option username 'vpnusername'
+ option password 'vpnpassword'
+ option server 'ipaddress'
+
+3, XL2TP:
+The following packages must be installed to use this protocol.
+ PACKAGE_ppp-multilink
+ PACKAGE_kmod-ppp
+ PACKAGE_xl2tpd
+
+example for create XL2TP:
+ # /etc/config/network
+ config interface 'vpn'
+ option ifname 'xl2tp-vpn'
+ option proto 'l2tp'
+ option username 'vpnusername'
+ option password 'vpnpassword'
+ option server 'ipaddress'
+
+4, Note that, for the above protocol, you also need to configure the rules in /etc/config/firewall.
+ # /etc/config/firewall
+ config zone
+ option name vpn
+ list network 'vpn'
+ option input ACCEPT
+ option output ACCEPT
+ option forward ACCEPT
+ option masq 1
+
+ config forwarding
+ option src lan
+ option dest vpn
+
+ config forwarding
+ option src vpn
+ option dest lan
+
+Additionally, the following rule should be configured for GRE tunnel.
+ config rule
+ option name Allow-GRE
+ option src wan
+ option proto gre
+ option target ACCEPT
+ option family ipv4
+
+
diff --git a/docs/marvell/howto/wireguad_client.txt b/docs/marvell/howto/wireguad_client.txt
new file mode 100644
index 0000000..13ba650
--- /dev/null
+++ b/docs/marvell/howto/wireguad_client.txt
@@ -0,0 +1,65 @@
+This how-to describes the method for setting up WireGuard client.
+========================================
+Here we take 1803 (i.e. Falcon) as example.
+The WireGuard server tested in this paper was created on Ubuntu 16.04.7 LTS.
+
+1) make menuconfig and select "CONFIG_PACKAGE_wireguard-tools" and save your new configuration.
+ make kernel_menuconfig and select "CONFIG_WIREGUARD" and save your new kernel configuration.
+And then rebuild：make -j8 V=99
+
+2) Key management
+ Generate and exchange keys between server and client.
+
+ # Generate keys
+ wg genkey | tee /tmp/wgserver.key | wg pubkey > /tmp/wgserver.pub
+ wg genkey | tee /tmp/wgclient.key | wg pubkey > /tmp/wgclient.pub
+
+ WG_KEY="$(cat /tmp/wgclient.key)" # Client private key
+ WG_PUB="$(cat /tmp/wgserver.pub)" # Server public key
+
+3) Firewall
+ Consider VPN network as public. Assign VPN interface to WAN zone to minimize firewall setup.
+
+ # Configure firewall
+ uci rename firewall.@zone[0]="lan"
+ uci rename firewall.@zone[1]="wan"
+ uci del_list firewall.wan.network="vpn"
+ uci add_list firewall.wan.network="vpn"
+ uci commit firewall
+ /etc/init.d/firewall restart
+
+
+4) Network
+ Configure VPN interface and peers.
+
+ # Configure network, WG_ADDR is the address of the WireGuard client,
+ # WG_KEY is the private key of the WireGuard client generated in 2)
+ uci -q delete network.vpn
+ uci set network.vpn="interface"
+ uci set network.vpn.proto="wireguard"
+ uci set network.vpn.private_key="${WG_KEY}"
+ uci add_list network.vpn.addresses="${WG_ADDR}"
+
+ # Add VPN peers, WG_PUB is the public key of the WireGuard server generated in Ubuntu 16.04.7 LTS.
+ # WG_SERV is the public IP address of the WireGuard server.
+ # WG_PORT is the wireguard udp port you use.
+ uci -q delete network.wgserver
+ uci set network.wgserver="wireguard_vpn
+ uci set network.wgserver.public_key="${WG_PUB}"
+ uci set network.wgserver.endpoint_host="${WG_SERV}"
+ uci set network.wgserver.endpoint_port="${WG_PORT}"
+ uci set network.wgserver.route_allowed_ips="1"
+ uci set network.wgserver.persistent_keepalive="25"
+ uci add_list network.wgserver.allowed_ips="0.0.0.0/0"
+ uci commit network
+ /etc/init.d/network restart
+
+
+
+5) Testing
+ Add the public key and IP address of the WireGuard client to server to establish the VPN connection.
+ # WG_ADDR is the address of the WireGuard client
+ # CLIENT_PUBLIC_KEY is the public key of the WireGuard client generated in 2), you can query it by "cat /tmp/wgclient.pub".
+ sudo wg set wg0 peer "${CLIENT_PUBLIC_KEY}" allowed-ips "${WG_ADDR}"
+
+ Use ping or traceroute to verify your WireGuard client can be accessed to server.
\ No newline at end of file
diff --git a/docs/marvell/howto/working_patches.pdf b/docs/marvell/howto/working_patches.pdf
new file mode 100644
index 0000000..114c8c5
--- /dev/null
+++ b/docs/marvell/howto/working_patches.pdf
Binary files differ
diff --git a/docs/marvell/howto/xlat464.txt b/docs/marvell/howto/xlat464.txt
new file mode 100644
index 0000000..98306d2
--- /dev/null
+++ b/docs/marvell/howto/xlat464.txt
@@ -0,0 +1,62 @@
+How to use the upstream XLAT464 function
+========================================
+For xlat464, we offer two solutions: one is the upstream xlat464 described in this document,
+and the other is based on datapath provided by ASR (see howto: data_path_nat46.txt).
+In contrast, the former converts nat46 and nat64 in the kernel, which will lose some throughput and cpu,
+while the latter can achieve zero copy, which can improve throughput.
+
+Here we take 1803 (i.e. Falcon) as example.
+The host PC system tested in this paper is Ubuntu 16.04.7 LTS.
+
+
+1) make menuconfig and select "PACKAGE_464xlat" and save your new configuration.
+And then rebuild：make -j8 V=99
+
+2) Redial using IPv6
+ "serial_client"
+ "AT+ZGDCONT=1,IPV6,GPRS"
+ "AT+ZGACT=1,1"
+ After this operation, you will not be able to access the IPv4 service and failed to ping IPv4 on the host or 1803,
+ but you can successfully ping the IPv6 server on 1803.
+
+3) Configure CLAT interface
+ # Configure network
+ uci set network.clat="interface"
+ uci set network.clat.proto="464xlat"
+ uci set network.clat.ip6prefix="64:ff9b::/96"
+ uci commit network
+ /etc/init.d/network reload
+
+ 64:ff9b::/96 is the v6 prefix of PLAT, which may not be accessible in china but is available overseas.
+
+4) Firewall
+ Consider CLAT network as public. Assign CLAT interface to WAN zone to minimize firewall setup.
+ # Configure firewall
+ uci rename firewall.@zone[1]="wan"
+ uci del_list firewall.wan.network="clat"
+ uci add_list firewall.wan.network="clat"
+ uci set firewall.wan.forward="ACCEPT"
+ uci commit firewall
+ /etc/init.d/firewall reload
+
+5) DHCP
+ If you need to resolve IPv6 domain names on Ubuntu, you need to configure IPv6 dns information in dhcp.
+ # Configure dhcp
+ list dns '2409:8030:2000::1'
+ list dns '2409:8030:2000::2'
+ uci add_list dhcp.lan.dns="2409:8030:2000::1"
+ uci add_list dhcp.lan.dns="2409:8030:2000::2"
+ uci commit dhcp
+ /etc/init.d/odhcpd restart
+
+ 2409:8030:2000::1 is the IPv6 dns you obtained by dialing, you can also set others, such as the gateway address of br-lan or Google dns.
+
+6) Host Configuration
+ "dhclient enp0s26u1u1"
+ "route add default gw 192.168.1.1"
+
+ enp0s26u1u1 is the enumerated rndis NIC on Ubuntu.
+
+7) Testing
+ Establish the XLAT connection. Use ping to verify your client can be accessed using IPv4.
+ ping www.baidu.com
diff --git a/docs/marvell/training/charger_fuelgauge.pdf b/docs/marvell/training/charger_fuelgauge.pdf
new file mode 100644
index 0000000..b6da146
--- /dev/null
+++ b/docs/marvell/training/charger_fuelgauge.pdf
Binary files differ
diff --git a/docs/marvell/training/display.pdf b/docs/marvell/training/display.pdf
new file mode 100644
index 0000000..229045f
--- /dev/null
+++ b/docs/marvell/training/display.pdf
Binary files differ
diff --git a/docs/marvell/training/linux_bsp.pdf b/docs/marvell/training/linux_bsp.pdf
new file mode 100644
index 0000000..45d7408
--- /dev/null
+++ b/docs/marvell/training/linux_bsp.pdf
Binary files differ
diff --git a/docs/marvell/training/network_mode_xml_tags_definition.pdf b/docs/marvell/training/network_mode_xml_tags_definition.pdf
new file mode 100644
index 0000000..2304d7a
--- /dev/null
+++ b/docs/marvell/training/network_mode_xml_tags_definition.pdf
Binary files differ
diff --git a/docs/marvell/training/ota.pdf b/docs/marvell/training/ota.pdf
new file mode 100644
index 0000000..fbaa2fb
--- /dev/null
+++ b/docs/marvell/training/ota.pdf
Binary files differ
diff --git a/docs/marvell/training/phonebook_xml_definition.pdf b/docs/marvell/training/phonebook_xml_definition.pdf
new file mode 100644
index 0000000..e9de725
--- /dev/null
+++ b/docs/marvell/training/phonebook_xml_definition.pdf
Binary files differ
diff --git a/docs/marvell/training/pin_mep_xml_tags_definition.pdf b/docs/marvell/training/pin_mep_xml_tags_definition.pdf
new file mode 100644
index 0000000..09acc1e
--- /dev/null
+++ b/docs/marvell/training/pin_mep_xml_tags_definition.pdf
Binary files differ
diff --git a/docs/marvell/training/pmu_guide.pdf b/docs/marvell/training/pmu_guide.pdf
new file mode 100644
index 0000000..232f615
--- /dev/null
+++ b/docs/marvell/training/pmu_guide.pdf
Binary files differ
diff --git a/docs/marvell/training/pxa1826_solution_long_overview.pdf b/docs/marvell/training/pxa1826_solution_long_overview.pdf
new file mode 100644
index 0000000..aca1d10
--- /dev/null
+++ b/docs/marvell/training/pxa1826_solution_long_overview.pdf
Binary files differ
diff --git a/docs/marvell/training/pxa1826_solution_overview.pdf b/docs/marvell/training/pxa1826_solution_overview.pdf
new file mode 100644
index 0000000..ce5f934
--- /dev/null
+++ b/docs/marvell/training/pxa1826_solution_overview.pdf
Binary files differ
diff --git a/docs/marvell/training/ril.pdf b/docs/marvell/training/ril.pdf
new file mode 100644
index 0000000..008a996
--- /dev/null
+++ b/docs/marvell/training/ril.pdf
Binary files differ
diff --git a/docs/marvell/training/sms_xml_tags.pdf b/docs/marvell/training/sms_xml_tags.pdf
new file mode 100644
index 0000000..85f836b
--- /dev/null
+++ b/docs/marvell/training/sms_xml_tags.pdf
Binary files differ
diff --git a/docs/marvell/training/telephony_modules.pdf b/docs/marvell/training/telephony_modules.pdf
new file mode 100644
index 0000000..2ea1771
--- /dev/null
+++ b/docs/marvell/training/telephony_modules.pdf
Binary files differ
diff --git a/docs/marvell/training/traffic_monitor.pdf b/docs/marvell/training/traffic_monitor.pdf
new file mode 100644
index 0000000..750b99b
--- /dev/null
+++ b/docs/marvell/training/traffic_monitor.pdf
Binary files differ
diff --git a/docs/marvell/training/usb.pdf b/docs/marvell/training/usb.pdf
new file mode 100644
index 0000000..3a1e56c
--- /dev/null
+++ b/docs/marvell/training/usb.pdf
Binary files differ
diff --git a/docs/marvell/training/web_services.pdf b/docs/marvell/training/web_services.pdf
new file mode 100644
index 0000000..047abb2
--- /dev/null
+++ b/docs/marvell/training/web_services.pdf
Binary files differ
diff --git a/docs/marvell/training/webui_flow.pdf b/docs/marvell/training/webui_flow.pdf
new file mode 100644
index 0000000..e8eae2b
--- /dev/null
+++ b/docs/marvell/training/webui_flow.pdf
Binary files differ
diff --git a/docs/marvell/training/webui_guide.pdf b/docs/marvell/training/webui_guide.pdf
new file mode 100644
index 0000000..08a0068
--- /dev/null
+++ b/docs/marvell/training/webui_guide.pdf
Binary files differ
diff --git a/docs/marvell/training/wifi.pdf b/docs/marvell/training/wifi.pdf
new file mode 100644
index 0000000..c828729
--- /dev/null
+++ b/docs/marvell/training/wifi.pdf
Binary files differ
diff --git a/docs/network-scripts.tex b/docs/network-scripts.tex
new file mode 100644
index 0000000..7ace975
--- /dev/null
+++ b/docs/network-scripts.tex
@@ -0,0 +1,55 @@
+\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
new file mode 100644
index 0000000..cf1200d
--- /dev/null
+++ b/docs/network.tex
@@ -0,0 +1,231 @@
+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
new file mode 100644
index 0000000..261af86
--- /dev/null
+++ b/docs/openwrt.sty
@@ -0,0 +1,10 @@
+\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
new file mode 100644
index 0000000..946387b
--- /dev/null
+++ b/docs/openwrt.tex
@@ -0,0 +1,41 @@
+\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
new file mode 100644
index 0000000..c16aaa9
--- /dev/null
+++ b/docs/submitting-patches.tex
@@ -0,0 +1,53 @@
+\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
new file mode 100644
index 0000000..efb07ea
--- /dev/null
+++ b/docs/wireless.tex
@@ -0,0 +1,492 @@
+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
new file mode 100644
index 0000000..3d3fc42
--- /dev/null
+++ b/docs/working.tex
@@ -0,0 +1,112 @@
+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 buysbox (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/buysbox/{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/buysbox/refresh QUILT=1
+\end{Verbatim}
