finally move buildroot-ng to trunk

3 files changed, 203 insertions, 0 deletions

diff --git a/docs/config.txt b/docs/config.txt
new file mode 100644
index 0000000..5988158
--- /dev/null
+++ b/docs/config.txt
@@ -0,0 +1,72 @@
+	== 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.txt b/docs/network-scripts.txt
new file mode 100644
index 0000000..024161b
--- /dev/null
+++ b/docs/network-scripts.txt
@@ -0,0 +1,52 @@
+	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.txt b/docs/network.txt
new file mode 100644
index 0000000..69dbaa6
--- /dev/null
+++ b/docs/network.txt
@@ -0,0 +1,79 @@
+	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.