Changeset 6a1aa6e8 in freewrt for docs

Timestamp:

Dec 13, 2006, 7:18:02 PM (19 years ago)

Author:

Phil Sutter <n0-1@…>

Branches:

freewrt_1_0, freewrt_2_0

Children:

1e874cf

Parents:

0665877

Message:

wrote some documentation about freewrt installation

git-svn-id: ​svn://www.freewrt.org/branches/freewrt_1_0@1294 afb5a338-a214-0410-bd46-81f09a774fd1

File:

• docs/handbook/user/00-allinone.tex (modified) (1 diff)

docs/handbook/user/00-allinone.tex

@@ -285 +285 @@
 \end{itemize}
 
-
-\chapter{The FreeWRT Operating System}
+\chapter{Installing FreeWRT Firmware Images}
+The FreeWRT ADK produces a single image holding both kernel and root
+filesystem. This image can be written into your hardware's builtin flash memory
+on serveral ways (ordered by needed skillz, increasing downwards):
+\begin{itemize} % TODO: insert \ref's to jump to the appropriate section?
+\item via the original firmware's web interface
+\item via \texttt{mtd} when reflashing or migrating from another $\star$WRT
+\item via network using a TFTP client
+\end{itemize}
+
+\section{Flashing The Firmware}
+
+\subsection{Web Interface Method}
+%TODO: may be filled in by someone who has done this before
+
+\subsection{\texttt{mtd} -- The Flash Utility}
+The \texttt{mtd} utility was written with simplicity and code size in mind.
+It's features were derived from the mtd-utils, %TODO: insert \ref to homepage
+combining the needed parts into a single small tool providing all the
+functionality necessary for FreeWRT, and leaving everything out that's not.
+
+\texttt{mtd} provides the following features:
+\begin{description}
+\item[unlock] some chips need unlocking before they can be written to
+\item[erase] this is a filesystem independent method to delete all contents on
+        the flash. Basically this is like \texttt{format} in MS--DOS.
+\item[write] this is generally the same functionality as using
+        \texttt{dd} or \texttt{rawrite}, but \texttt{mtd} takes care of the quirks
+        that have to be paid attention to for correctly handling the type of flash
+        in use
+\end{description}
+further it can request your system to reboot. Some of the features mentioned here can
+also be combined, so it is e.g. possible to immediately reboot the system after
+the flash has been written.
+
+\begin{center}\fbox{\parbox{30em}{
+\textbf{No \texttt{mtd} utility available?} \\
+There is one built statically for those situations, so you can just
+\texttt{scp} it to the device and use it standalone. 
+% TODO: describe where to find it/how to build it
+}}\end{center}
+
+Mostly, the sample usage shown in the help output should be all that has to be
+done to write the firmware to flash:
+\begin{Verbatim}
+# mtd -r write linux.trx linux
+\end{Verbatim}
+The parameters explained in detail: \\
+\begin{tabular}{l|l}
+$-r$ & trigger rebooting right after finishing work \\
+write & write the firmware image contained in the file given as next parameter
+                        to flash \\
+linux.trx & the actual image to write - ignore the suffix, it is detected at
+                                runtime \\
+linux & this is an abstract identifier for a certain partition in flash, so
+don't change this \\
+\end{tabular}
+
+\subsection{Installation using TFTP}
+All supported target devices are shipped with a builtin firmware, comparable to
+the BIOS of x86--machines. This firmware is used to bootstrap the system until
+it can boot a regular operating system. Besides the (obvious) ability to load
+the executable code from flash, it can be received from another node in the
+local area network via the famous TFTP protocol. 
+
+For doing this, there are two ways: \\
+\begin{itemize}
+\item the device acts as a client, asks the local dhcpd for a lease, the
+address of the next tftpd and the filename to download
+\item the device acts as a server, having a known IP address and waiting for
+any TFTP client to connect and send the file
+\end{itemize}
+All the hardware supported by FreeWRT-1.0 uses the second method. % TODO: righty?
+Though this may be a little confusing to people being familiar with netboot
+technologies, it is definitely the easier way of doing it. Otherwise one had to
+setup both DHCP and TFTP servers and configure them right.
+
+The even quite simple task of sending the flash image to the target device is
+made even more easy by providing a little shell script for the job. Invocation
+is as follows:
+\begin{Verbatim}
+$ ./scripts/flash.sh firmware.bin [address] 
+\end{Verbatim} 
+The second Parameter \textit{address} is used to specify a different IP address
+of the target device than the default \textit{192.168.1.1}.
+
+\textbf{Beware:} do not rename the firmware image before flashing it using the
+script as the original name is parsed to guess what hardware is to be flashed.
+
+To actually being able to flash the device, it has to wait for a tftp
+connection when booting. To complicate installation of third vendor's firmware
+images and to improve bootup time, of course, this feature is disabled by
+default. The following list shows what has to be done for a certain device to
+get it to wait at boot: \\
+\begin{center}\begin{tabular}{l|l|l} % TODO: fill this table
+\textbf{Target Device} & \textbf{Action to be taken} & \textbf{Comments} \\
+\hline
+\ldots & \ldots & \ldots \\
+\end{tabular}\end{center}
+
+\chapter{FreeWRT Administration}
 After the FreeWRT firmware image has been built by the ADK and later flashed
 onto the hardware, the resulting operating system has to be aministrated. This