wifi docs: fix a few typos and inconsistencies, add examples

[openwrt/staging/dedeckeh.git] / docs / wireless.tex

diff --git a/docs/wireless.tex b/docs/wireless.tex
index 861e04dc464ea40a9839db66c0b94762acb6eb8a..5734fc093b20157cb8e08286d6901445f3afa48c 100644 (file)
--- a/docs/wireless.tex
+++ b/docs/wireless.tex
@@ -235,30 +235,84 @@ include several functions providing :
 
 Each driver script should append the driver to a global DRIVERS variable :
 
-\begin{verbatim}
+\begin{Verbatim}
 append DRIVERS "driver name"
-\end{verbatim}
+\end{Verbatim}
 
-\subparagraph{scan\_driver}
+\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 enable your wireless driver to work.
+options. It does not change the state of the interface.
 
-\subparagraph{enable\_driver}
+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}
 
-This function will enable the driver and read the configuration file to create application
-specific configuration files for the NAS or supplicant program. It will not check the
-configuration consistency.
+\subparagraph{\texttt{enable\_<driver>}}
 
-\subparagraph{disable\_driver}
+This function will bring up the wifi device and optionally create application specific
+configuration files, e.g. for the WPA authenticator or supplicant.
 
-This function should properly shutdown the wireless interfaces and kill associated programs
-running on top of it.
+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{detec\_driver}
+\subparagraph{\texttt{disable\_<driver>}}
 
-This function should reliably report the existence of the driver and of one or more of its
-wireless interfaces. A basic configuration file has to be generated in the meantime.
+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}