add initial version of our new documentation - not too pretty yet, but will be improved

SVN-Revision: 5060

8 files changed, 279 insertions, 203 deletions

diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..0a41287
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,15 @@
+openwrt.pdf: Makefile openwrt.tex config.tex network.tex network-scripts.tex
+	$(MAKE) cleanup
+	pdflatex openwrt.tex
+	pdflatex openwrt.tex
+	$(MAKE) cleanup
+	
+clean: cleanup
+	rm -f openwrt.pdf
+
+cleanup: FORCE
+	rm -f *.log *.aux *.toc
+
+
+FORCE:
+.PHONY: FORCE
diff --git a/docs/config.tex b/docs/config.tex
new file mode 100644
index 0000000..44b6689
--- /dev/null
+++ b/docs/config.tex
@@ -0,0 +1,79 @@
+\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}
+. /etc/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{/etc/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.
+
+You can access already processed options with the \texttt{config\_get} command
+Syntax:
+
+\begin{Verbatim}
+config_get <section> <option>            # prints the value of the option
+config_get <variable> <section> <option> # stores the value inside the variable
+\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}
+
diff --git a/docs/config.txt b/docs/config.txt
deleted file mode 100644
index 5988158..0000000
--- a/docs/config.txt
+++ /dev/null
@@ -1,72 +0,0 @@
-	== 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:
-
-config <type> [<name>]			# Section
-	option <name>	<value>		# Option
-
-
-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.
-
-
-
-	== Parsing configuration files in custom scripts ==
-
-To be able to load configuration files, you need to include the common 
-functions with:
-
-. /etc/functions.sh
-
-Then you can use config_load <name> to load config files. The function 
-first checks for <name> as absolute filename and falls back to loading 
-it from /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 config_load
-(after including /etc/functions.sh):
-
-config_cb() {
-	local type="$1"
-	local name="$2"
-	# commands to be run for every section
-}
-
-option_cb() {
-	# commands to be run for every option
-}
-
-You can also alter option_cb from config_cb based on the section type.
-This allows you to process every single config section based on its type
-individually.
-
-config_cb is run every time a new section starts (before options are being
-processed). You can access the last section through the CONFIG_SECTION
-variable. Also an extra call to config_cb (without a new section) is generated
-after config_load is done.
-That allows you to process sections both before and after all options were
-processed.
-
-You can access already processed options with the config_get command
-Syntax:
-
-config_get <section> <option>            # prints the value of the option
-config_get <variable> <section> <option> # stores the value inside the variable
-
-In busybox ash the three-option 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 
-config_set command.
-
-Syntax:
-
-config_set <section> <option> <value>
-
diff --git a/docs/network-scripts.tex b/docs/network-scripts.tex
new file mode 100644
index 0000000..79a8853
--- /dev/null
+++ b/docs/network-scripts.tex
@@ -0,0 +1,54 @@
+\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}
+. /etc/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 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-scripts.txt b/docs/network-scripts.txt
deleted file mode 100644
index 024161b..0000000
--- a/docs/network-scripts.txt
+++ /dev/null
@@ -1,52 +0,0 @@
-	Structure of the network scripts in buildroot-ng
-
-
-1) Usage
-
-To be able to access the network functions, you need to include
-the necessary shell scripts by running:
-
-. /etc/functions.sh      # common functions
-include /lib/network     # include /lib/network/*.sh
-scan_interfaces          # read and parse the network config
-
-Some protocols, such as PPP might change the configured interface names
-at run time (e.g. eth0 => ppp0 for PPPoE). That's why you have to run
-scan_interfaces instead of reading the values from the config directly.
-After running scan_interfaces, the '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 'device'
-option.
-That means that running 'config_get lan ifname' after scan_interfaces
-might not return the same result as running it before.
-
-After running scan_interfaces, the following functions are available:
-
-- find_config <interface> looks for a network configuration that includes
-  the specified network interface.
-
-- setup_interface <interface> [<config>] [<protocol>] will set up the
-  specified interface, optionally overriding the network configuration
-  name or the protocol that it uses.
-
-
-
-2) Writing protocol handlers
-
-You can add custom protocol handlers by adding shell scripts to
-/lib/network. They provide the following two shell functions:
-
-scan_<protocolname>() {
-	local config="$1"
-	# change the interface names if necessary
-}
-
-setup_interface_<protocolname>() {
-	local interface="$1"
-	local config="$2"
-	# set up the interface
-}
-
-scan_<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..1ba1bd9
--- /dev/null
+++ b/docs/network.tex
@@ -0,0 +1,86 @@
+The network configuration in Kamikaze 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.1}. These can be nested as well.
+
+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.
+DHCP currently only accepts \texttt{ipaddr} (IP address to request from the server)
+and \texttt{hostname} (client hostname identify as) - both are optional.
+
+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.
+
+
+\subsubsection{Setting up the switch (currently 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.
diff --git a/docs/network.txt b/docs/network.txt
deleted file mode 100644
index 69dbaa6..0000000
--- a/docs/network.txt
+++ /dev/null
@@ -1,79 +0,0 @@
-	Network configuration in buildroot-ng
-
-
-The network configuration in buildroot-ng is stored in /etc/config/network
-and is divided into interface configurations.
-Each interface configuration either refers directly to an ethernet/wifi
-interface (eth0, wl0, ..) or to a bridge containing multiple interfaces.
-It looks like this:
-
-	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"
-
-"ifname" specifies the Linux interface name.
-If you want to use bridging on one or more interfaces, set "ifname" to a list
-of interfaces and add:
-		option type 	"bridge"
-
-It is possible to use VLAN tagging on an interface simply by adding the VLAN IDs
-to it, e.g. "eth0.1". These can be nested as well.
-
-This sets up a simple static configuration for eth0. "proto" specifies the
-'protocol' used for the interface. The default image usually provides 'none'
-'static', 'dhcp' and 'pppoe'. Others can be added by installing additional
-packages.
-
-When using the 'static' method like in the example, the  options "ipaddr" and 
-"netmask" are mandatory, while "gateway" and "dns" are optional.
-DHCP currently only accepts "ipaddr" (IP address to request from the server)
-and "hostname" (client hostname identify as) - both are optional.
-
-PPP based protocols (pppoe, pptp, ...) accept these options:
-	username:
-		The PPP username (usually with PAP authentication)
-	password:
-		The PPP password
-	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
-	demand:
-		Use Dial on Demand (value specifies the maximum idle time)
-		
-	(pptp)
-	server: The remote pptp server IP
-
-For all protocol types, you can also specify the MTU by using the "mtu" option.
-
-
-
-
-	Setting up the switch (currently broadcom only)
-
-
-The switch configuration is set by adding a 'switch' config section.
-Example: 
-
-	config switch eth0
-		option vlan0 "1 2 3 4 5*"
-		option vlan1 "0 5"
-
-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:
-
-	'*': Set the default VLAN (PVID) of the Port to the current VLAN
-	'u': Force the port to be untagged
-	't': Force the port to be tagged
-
-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.
diff --git a/docs/openwrt.tex b/docs/openwrt.tex
new file mode 100644
index 0000000..6eda7c0
--- /dev/null
+++ b/docs/openwrt.tex
@@ -0,0 +1,45 @@
+\documentclass[a4paper]{book}
+\usepackage[latin9]{inputenc}
+%\usepackage[T1]{fontenc}
+\usepackage{fancyvrb}
+
+\begin{document}
+
+\tableofcontents
+
+\chapter{The Router}
+\section{Getting started}
+\subsection{Installation}
+\subsection{Initial configuration}
+\subsection{Failsafe mode}
+\section{Configuring OpenWrt}
+\subsection{Network}
+\include{network}
+
+\subsection{Wireless}
+
+\section{Advanced configuration}
+\include{config}
+
+\subsection{Hotplug}
+\subsection{Init scripts}
+\subsection{Network scripts}
+\include{network-scripts}
+
+\chapter{Development issues}
+\section{The build system}
+\subsection{Building an image}
+\subsection{Integrating packages}
+\subsection{Creating packages}
+
+\section{Extra tools}
+\subsection{Image Builder}
+\subsection{SDK}
+
+\section{Adding platform support}
+\section{Debugging and debricking}
+\subsection{Adding a serial port}
+\subsection{JTAG}
+
+
+\end{document}