source: freewrt/Docs/handbook/devel/handbook-dev.tex@ 4c593d5

\documentclass[12pt,a4paper,openany,smallheadings,
headinclude,headsepline,final]{scrreprt}
\usepackage[utf8]{inputenc}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{caption2}
\usepackage[canadian]{babel}
\usepackage{varioref}
\usepackage{txfonts}
\usepackage[pdftex]{graphicx}
\usepackage{makeidx}
\usepackage[T1]{fontenc}

% fancy verbatim enables changing of font, fontsize, etc. in verbatim code
% also set smaller font and a frame as default
\usepackage{fancyvrb}
\fvset{fontsize=\small, frame=single}

% marvosym macht Pfeil kaputt, also sichern
% line 28, /usr/share/texmf/tex/latex/marvosym/marvosym.sty
\let\RescueRightarrow=\Rightarrow
\usepackage{marvosym}
\renewcommand{\Rightarrow}{\RescueRightarrow}

\usepackage[pdftex]{color}
\definecolor{skyblue}{rgb}{0,0.3323,0.5720}
\usepackage[%
colorlinks=true,anchorcolor=red,
breaklinks=true,linkcolor=blue,urlcolor=red,
citecolor=skyblue,
pdfauthor={The FreeWRT Team},
pdftitle={FreeWRT Developer Handbook},
pdfcreator={tetex and VIM},
pdfsubject={Open Source},
pdfview=FitV,
pdfstartview=FitV,
pdfstartpage={1},
pdfpagelayout=SinglePage,
pdfpagemode=None,
pdfkeywords={FreeWRT}]{hyperref}
%\usepackage{thumbpdf}
\usepackage{cancel}
%\usepackage[final, activate, verbose=true]{microtype}
\usepackage{ngerman}
%\usepackage{bookman}
%\usepackage[a4paper,twoside,rmargin=2cm,lmargin=2cm,tmargin=2.5cm]{geometry}
\usepackage[a4paper,rmargin=2cm,lmargin=2cm,tmargin=2.5cm,bmargin=2.5cm]{geometry}
%\usepackage{ncntrsbk}
\usepackage{float}
\restylefloat{figure}
%\bibliographystyle{alphadin}
\bibliographystyle{alpha}

% Change Section, Chapter Layout
% http://www.mackichan.com/index.html?techtalk/518.htm~mainFrame
%\usepackage{sectsty}
%\allsectionsfont{\raggedleft}
%\chapterfont{\raggedleft}

% BEGIN Fancy Header Extensions
% Save Graphics in Latex box
%\renewcommand{\headheight}{30pt} %Make height wider so picture is ok
%\renewcommand{\footskip}{45pt} %Make height wider so picture is ok

\usepackage{fixltx2e, mparhack}

% Generate index in preamble
\makeindex
\begin{document}
\setlength{\marginparwidth}{10mm}
\include{cover}
\renewcommand{\thepage}{\roman{page}}
\tableofcontents
%Set Arabic Numbering 1,2,3,...
% Clear needed to renumber from the right position
\cleardoublepage
\renewcommand{\thepage}{\arabic{page}}
%Reset Counter
%\setcounter{page}{1}

% Set marks where it should Change
\renewcommand{\chaptermark}[1]{%
\markboth{\large \thechapter.\ \normalsize \scshape #1}{}}
\renewcommand{\sectionmark}[1]{\markright{\thesection.\ \scshape #1}}

\newcommand{\blitz}{ \Lightning }
\newcommand{\entspr}{\stackrel{\wedge}{=}}

\chapter{Introduction}

Welcome to FreeWRT! This handbook covers all aspects of the Appliance Development
Kit from a view of an embedded system developer. FreeWRT is a portable, secure and
functional Linux distribution for embedded systems. As FreeWRT is a source code
distribution, it does not provide any pre-compiled firmware for embedded systems.
The latest version of this document is always available at the FreeWRT website.
This book describes the ADK for FreeWRT 1.1 and maybe later.

If you have any comments, criticism or found some wrong description, please send
us an e-mail to freewrt-handbook@freewrt.org, we are always happy about getting
feedback and will try to update or correct the issues mentioned by you.

The FreeWRT developer handbook is split into five distinct sections. 
% ADK Overview
% SVN Grundlagen
% Paket Portieren
% Troubleshooting (uclibc limits, dns stuff, libnotimpl, fpu, asm, host mixup )
% Strace, Debugging via GDBServer
% ADK in detail, Kernel Buildsystem
% New Embedded System (Etrax)

The first chapter will give you an overview to the Appliance Development Kit.
The second chapter, Using SVN, will describe some basics about subversion.
Useful if you work with the ADK and want to send your improvements or new
packages back to the FreeWRT project.  After that we will port a application to
show the simplicity of doing this with the FreeWRT ADK.  The fourth chapter
will contain information about troubleshooting compile time problems, the fifth
chapter contains helpful information about debugging runtime problems. After
that we will give detailed instructions about the inner structure of the ADK.
In our last chapter we describe how to integrate a new embedded system into the
ADK.

The intended audience for this handbook are embedded systems developers with
deep knowledge about Linux hacking. It is aimed for developers who would like
to port software to FreeWRT, like to create an Linux-based appliance or need
information about debugging compile or runtime problems on the FreeWRT Linux
distribution.

\section{Typographic Conventions}

Examples starting with \# indicate a command that must be invoked as super
user. You can use su to gain super user privileges.

\begin{Verbatim}
# gdbserver /usr/bin/vim
\end{Verbatim}

Examples starting with \$ indicate a command that should be invoked as a
unprivileged user.  

\begin{Verbatim}
$ make
\end{Verbatim}

\chapter{Appliance Development Kit (ADK) Overview}

The ADK is the core of FreeWRT. It contains all the magic to create the FreeWRT
firmware for your embedded system. It will download the needed software
packages from the internet and will prepare, compile and combine all components
into a ready-to-go firmware image. The ADK is a combination of Makefiles, the
Kernel 2.6 configuration system, shell scripts and some other helper
applications.

\section{Prerequisites}

Before you can start with the ADK you need to check if you have one of the
supported Hostsystems and have installed the needed software for that.  Here is
a list of all supported and tested host systems. The host system is needed to
create a firmware for your embedded system.

The list of supported GNU/Linux build systems is not an exclusive one, these
are just the ones tested and verified. The other millions of linux
distributions are very likely to work, too.

\begin{itemize}
\item Debian GNU/Linux
\item Gentoo Linux
\item OpenSuSE 
\item Ubuntu GNU/Linux
\item Fedora Core 
\item OpenBSD (partial support)\footnote{some addon packages does not compile}
\item MirOS BSD (partial support)\footnote{some addon packages does not compile}
\end{itemize}

Please install the following software, which is needed to build a basic
firmware image. If you choose more packages some more prerequisites might be
needed. The ADK host checks will warn you about any software you need to install to
compile a specific package.  Here is a list of the required software:

\begin{itemize}
\item gcc3 or higher
\item g++
\item binutils
\item patch
\item gzip
\item bzip2
\item unzip
\item flex
\item bison
\item zlib (+headers)
\item ncurses (+headers)
\item (g)libc headers
\end{itemize}

The ADK scripts will check for the required versions of these tools in advance.

To build FreeWRT with the ADK it is recommended to have an unprivileged
user. Please \underline{never} build FreeWRT as super user. Because all necessary source
tarballs are downloaded from the internet automatically, your host system
needs a working internet connection.

\section{Details Of Cross-Compiling}

A cross-compile toolchain exists of a set of tools: a compiler, linker, assembler,
debugger and a c library. A cross-compile toolchain runs on your host system and
creates native binaries for your target system. A cross-compile toolchain is
basically created in six steps:

\begin{enumerate}
\item Get and prepare the Kernel and C Library headers of your target system
\item Compile the binutils package for your target
\item Compile a static C compiler for your target
\item Compile and install a C library for your target
\item Compile and install a full C/C++ compiler
\item Compile and install the GNU debugger
\end{enumerate}

The cross-compile toolchain is created in
,,staging\_dir\_\$(cpu\_arch)''\footnote{f.e. mipsel, which stands for MIPS Little
Endian)}.  All the tools running on the host, but used to create, analyze or debug
for the target are kept in this directory. All addon headers and libraries
are installed to this directory.

If you want to compile a simple application without using the ADK, just use the
compiler directly (f.e. compiling a MIPS Little Endian application):
\begin{verbatim}
./staging_dir_mipsel/bin/mipsel-linux-uclibc-gcc -o myapp myapp.c
\end{verbatim}

Check with ,,file'' if you got a MIPS binary:
\begin{verbatim}
$ file myapp
myapp: ELF 32-bit LSB MIPS-I executable, MIPS, version 1 (SYSV), dynamically
linked (uses shared libs), not stripped
\end{verbatim}

\section{Firmware Build Process}

Just like when building the ADK's toolchain, the sources for the selected
packages are downloaded from the internet first, then build using the
cross-compiler and libraries of the ADK.

The detailed order of firmware image building is:

\begin{itemize}
\item compile the Linux kernel and all supported kernel modules
\item compile all selected packages
\item clean the target root directory
\item install all packages to the target root directory
\item create the root filesystem image
\item create the firmware image (bootloader, kernel and root filesystem)
\end{itemize}

The result of the build process is created in the ,,bin'' directory.  You will
find a firmware image in the top level directory.  Furthermore there is a
,,package'' directory, which contains all base and addon packages.


\chapter{Using Subversion}

\section{Getting the source}

Go to a directory where you want to checkout the ADK. 
To get the latest version of the FreeWRT ADK use one of these commands:
\begin{Verbatim}
$ svn co http://www.freewrt.org/svn/trunk freewrt
$ svn co svn://www.freewrt.org/trunk freewrt
\end{Verbatim}

After successfully downloading, enter the directory:

\begin{Verbatim}
$ cd freewrt
\end{Verbatim}

This directory will be referred to as the ADK root directory later on.

\chapter{Porting an application}

% strongswan?

\section{Using a package template}

\chapter{Troubleshooting compile time problems}

% other projects (Gentoo, OpenWrt, OpenEmbedded, *BSD ports)

\chapter{Troubleshooting runtime problems}

% other projects (Gentoo, OpenWrt, OpenEmbedded, *BSD ports)
% Upstream Bugtracking and Mailinglist archives

% gdbserver
% strace
% logging (logread, ...), verbose mode, non-fork

% compile the application with -g
% disable -O flags
% disable -fomit-frame-pointer

% install gdbserver package
% gdbserver /usr/bin/vim


\begin{verbatim}
Target system:
admin@FreeWRT:~$ /usr/bin/gdbserver 192.168.42.1:10000 /usr/bin/vim
Process /usr/bin/vim created; pid = 440
Listening on port 10000


Host system:
cd build_mipsel/w-vim-5.8/vim-5.8
~/freewrt/staging_dir_mipsel/bin/mipsel-linux-gdb vim
(gdb) target extended-remote 192.168.42.1:10000
Remote debugging using 192.168.42.1:10000
0x2aaa8ac0 in ?? ()
warning: Unable to find dynamic linker breakpoint function.
GDB will be unable to debug shared library initializers
and track explicitly loaded dynamic code.

(gdb) dir .
(gdb) set solib-absolute-prefix ~/staging_dir_mipsel
(gdb) continue
Continuing.

Program received signal SIGSEGV, Segmentation fault.
0x0044efa0 in op_yank (oap=0x7fff7d18, deleting=7, mess=1) at ops.c:2388
2388        curbuf->b_op_start = oap->start;
(gdb) bt
#0  0x0044efa0 in op_yank (oap=0x7fff7d18, deleting=7, mess=1) at ops.c:2388
#1  0x004452bc in do_pending_operator (cap=0x7fff7c40, searchbuff=0x10006010 "", 
    command_busy=0x7fff7c90, old_col=0, gui_yank=0, dont_adjust_op_end=646447176)
    at normal.c:1789
#2  0x0044c780 in normal_cmd (oap=0x7fff7d18, toplevel=1) at normal.c:1277
#3  0x00431490 in main (argc=2147450136, argv=0x10005ff0) at main.c:1573


\end{verbatim}

\chapter{Appliance Development Kit (ADK) Reference}

\section{Filesystem structure}

After a fresh checkout you get following file and directory structure in your 
working directory:
\begin{verbatim}
docs
mk
target
tools
toolchain
package
scripts
Config.in
Makefile
\end{verbatim}

You will see some more files there, containing license information, portability
code for different make implementations or some special files for automatic 
builds. We will concentrate on the above list for now.

The docs/ directory contains a package template and the FreeWRT handbook's
as LaTeX source code. 

\section{NFO system}


\section{Kernel buildsystem}




\chapter{Integration of a new embedded system into ADK}

This is a chapter with many practical advices and code. We will describe in detail
how the Foxboard was added to the FreeWRT ADK.  The Foxboard is choosen, because
it is not yet ported in other embedded projects and has many differences to
existing supported systems. Therefore we need to go through all aspects needed
to support the Foxboard in the FreeWRT ADK.

\section{Information Gathering}

% CPU, ARCH, RAM, Flash, Filesystems

\section{ADK variables}

% CPU, Endianess, Kernel version, Boardshortname


\section{Toolchain}

\section{Bootloader}

\section{Kernel}

% versions supported? 2.4 / 2.6
% patches from vendors?

\section{Filesystems}

% different kinds of possibilities 
% squashfs, lzma, jffs2, yaffs2, ext2, nfs

\section{Firmware Images}

\section{Drivers}

% always builtin all essential drivers
% make packages for all non-essential drivers

\section{Boardspecific Packages}

% external packages for drivers
% binary only drivers

\chapter{FreeWRT policy for submissions}

- runtime tests
- package quality, add startup scripts, provide subpackages if useful
- clean patches, why you have changed sth, not how

\end{document}