Base files

10 files changed, 1151 insertions, 25 deletions

diff --git a/doc/bsp_howto/Makefile b/doc/bsp_howto/Makefile
index 39b0b0d1f6..d258548d73 100644
--- a/doc/bsp_howto/Makefile
+++ b/doc/bsp_howto/Makefile
@@ -6,7 +6,7 @@
 #  $Id$
 #
 
-PROJECT=started
+PROJECT=bsp_howto
 DISTRIBUTION_LEVEL=public
 
 include ../Make.config
@@ -18,8 +18,8 @@ dirs:
 
 COMMON_FILES=../common/cpright.texi ../common/setup.texi
 
-GENERATED_FILES= buildc.texi buildrt.texi gdb.texi intro.texi \
-    nt.texi require.texi sample.texi
+GENERATED_FILES= clock.texi console.texi init.texi intro.texi \
+    linkcmds.texi bspstruct.texi makefiles.texi target.texi timer.texi
 
 FILES= $(PROJECT).texi versions.texi $(GENERATED_FILES)
 
@@ -44,45 +44,53 @@ $(PROJECT).dvi: $(FILES)
 	$(TEXI2DVI) -v $(PROJECT).texi
 	texi2dvi -v $(PROJECT).texi
 
-intro.texi: intro.t versions.texi
-	$(BMENU) -c -p "Top" \
+intro.texi: intro.t Makefile
+	$(BMENU) -c -p "" \
 	    -u "Top" \
-	    -n "Requirements" ${*}.t
+	    -n "" ${*}.t
+
+target.texi: target.t Makefile
+	$(BMENU) -c -p "" \
+	    -u "Top" \
+	    -n "" ${*}.t
+
+bspstruct.texi: bspstruct.t Makefile
+	$(BMENU) -c -p "" \
+	    -u "Top" \
+	    -n "" ${*}.t
 
-require.texi: require.t versions.texi
-	$(BMENU) -c -p "EGCS Mailing List" \
+makefiles.texi: makefiles.t Makefile
+	$(BMENU) -c -p "" \
 	    -u "Top" \
-	    -n "Building the GNU C/C++ Cross Compiler Toolset" ${*}.t
+	    -n "" ${*}.t
 
-buildc.texi: buildc.t versions.texi
-	$(BMENU) -c -p "Requirements" \
+linkcmds.texi: linkcmds.t Makefile
+	$(BMENU) -c -p "" \
 	    -u "Top" \
-	    -n "Building RTEMS" ${*}.t
+	    -n "" ${*}.t
 
-buildrt.texi: buildrt.t versions.texi
-	$(BMENU) -c -p "Running the bit Script" \
+init.texi: init.t Makefile
+	$(BMENU) -c -p "" \
 	    -u "Top" \
-	    -n "Building the Sample Application" ${*}.t
+	    -n "" ${*}.t
 
-sample.texi: sample.t versions.texi
-	$(BMENU) -c -p "Generate RTEMS for a Specific Target and BSP" \
+clock.texi: clock.t Makefile
+	$(BMENU) -c -p "" \
 	    -u "Top" \
-	    -n "Building the GNU Debugger" ${*}.t
+	    -n "" ${*}.t
 
-gdb.texi: gdb.t versions.texi
-	$(BMENU) -c -p "Application Executable" \
+console.texi: console.t Makefile
+	$(BMENU) -c -p "" \
 	    -u "Top" \
-	    -n "Using MS-Windows as a Development Host" ${*}.t
+	    -n "" ${*}.t
 
-nt.texi: nt.t versions.texi
-	$(BMENU) -c -p "GDB for DINK32" \
+timer.texi: timer.t Makefile
+	$(BMENU) -c -p "" \
 	    -u "Top" \
 	    -n "" ${*}.t
 
 html: dirs $(FILES)
 	-mkdir -p $(WWW_INSTALL)/$(PROJECT)
-	-cp pictures/sfile12c.jpg $(WWW_INSTALL)/$(PROJECT)
-	-cp pictures/bit_c.jpg $(WWW_INSTALL)/$(PROJECT)
 	$(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \
  	    $(PROJECT).texi
 
diff --git a/doc/bsp_howto/bspstruct.t b/doc/bsp_howto/bspstruct.t
new file mode 100644
index 0000000000..cd42da28e3
--- /dev/null
+++ b/doc/bsp_howto/bspstruct.t
@@ -0,0 +1,37 @@
+@chapter =  The Board Support Package Structure
+
+The BSP are all kept in the $RTEMS_ROOT/c/src/lib/libbsp directory. They
+are filed under the processor family (m68k, powerpc, etc.). A given BSP
+consists in the following directories: 
+
+@itemize @bullet
+
+@item clock : support for the realtime clock, which provides a regular
+time basis to the kernel,
+
+@item console : rather the serial driver than only a console driver, it
+deals with the board UARTs (i.e. serial devices),
+
+@item include : the include files,
+
+@item startup : the board initialization code,
+
+@item timer : support of timer devices,
+
+@item shmsupp : support of shared memory in a multiprocessor system,
+
+@item network : the KA9Q ethernet driver. 
+
+@end itemize
+
+Another important element are the makefiles, which have to be provided by
+the user. 
+
+
+Rem : You should have a copy of the gen68340 BSP
+($RTEMS_ROOT/c/src/lib/libbsp/m68k/gen68340) in hand while reading this
+piece of documentation. 
+
+Further in this document we'll use the $BSP340_ROOT label for
+$RTEMS_ROOT/c/src/lib/libbsp/m68k/gen68340. 
+
diff --git a/doc/bsp_howto/clock.t b/doc/bsp_howto/clock.t
new file mode 100644
index 0000000000..403192fd32
--- /dev/null
+++ b/doc/bsp_howto/clock.t
@@ -0,0 +1,38 @@
+@chapter = The Clock Driver
+
+@subsection = Introduction
+
+The clock driver aims at giving a steady time basis to the kernel, so that
+the RTEMS primitives that need a clock tick work properly. <insert a link
+to the Clock Driver defs>
+
+The clock driver is located in the clock directory of the BSP. 
+
+@subsection = Primitives
+
+@subsection = Initialization
+
+The major and minor numbers of the clock driver can be made available to
+the others, such as the Shared Memory Driver. 
+
+Then you have to program your integrated processor periodic interval timer
+so that an interrupt is generated every m microseconds, where m =
+BSP_Configuration.microseconds_per_tick. Sometimes the periodic interval
+timer can use a prescaler so you have to look carefully at your user's
+manual to determine the correct value. 
+
+You must use the RTEMS primitive to put your clock interrupt routine in
+the VBR: 
+
+@example
+rtems_interrupt_catch (InterruptHandler, CONSOLE_VECTOR, &old_handler); 
+@end example
+
+@subsection = The clock interrupt subroutine
+
+It only has to inform the kernel that a ticker has elapsed, so call : 
+
+@example
+rtems_clock_tick(); 
+@end example
+
diff --git a/doc/bsp_howto/console.t b/doc/bsp_howto/console.t
new file mode 100644
index 0000000000..9aa3132bc3
--- /dev/null
+++ b/doc/bsp_howto/console.t
@@ -0,0 +1,266 @@
+@chapter = The Console Driver
+
+@subsection = Introduction
+
+This chapter describes how to do a console driver using RTEMS Termios
+support. 
+
+The serial driver is called as soon as printf/scanf or read/write kind of
+input/output are needed. There are two main functioning modes: 
+
+@itemize @bullet
+
+@item console: formatted input/output, with special characters (end of
+line, tabulations, etc...) recognition and processing,
+
+@item raw: permits raw data processing. 
+
+@end itemize
+
+We may think that one need two serial drivers to deal with those two types
+of data, but Termios permits having only one driver. 
+
+@subsection = Termios
+
+Termios is a standard for terminal management, included in several Unix
+versions. Termios is good because: 
+
+@itemize @bullet
+
+@item from the user's side: primitives to access the terminal and change
+configuration settings are the same under Unix and Rtems. 
+
+@item from the BSP developer's side: it frees you from dealing with buffer
+states and mutual exclusions on them. 
+
+@end itemize
+
+Termios support includes: 
+
+@itemize @bullet
+
+@item raw and console handling,
+
+@item blocking or non-blocking characters receive, with or without
+Timeout. 
+
+@end itemize
+
+For more information on Termios, type man termios in your Unix box or go
+to http://www.freebsd.org/cgi/man.cgi. 
+
+@subsection = Driver Functioning Modes
+
+There are generally two main functioning modes for an UART (Universal
+Asynchronous Receiver-Transmitter, i.e. the serial chip): 
+
+@itemize @bullet
+
+@item polling mode: the processor blocks on sending/receiving characters.
+This mode is not powerful, but is necessary when one wants to print an
+error message when the board hung. This is also the most simple mode to
+program,
+
+@item interrupt mode: the processor doesn't block on sending/receiving
+characters. Two buffers (one for the in-going characters, the others for
+the characters to be sent) are used. An interrupt is raised as soon as a
+character is in the UART. Then the int errupt subroutine insert the
+character at the input buffer queue. When a character is asked for input,
+this at the head of the buffer is returned. When characters have to be
+sent, one have to put the first characters (the number depends on the
+UART) in th e UART. Then an interrupt is raised when all the characters
+have been emitted. The interrupt subroutine has to send the characters
+remaining in the output buffer the same way. 
+
+@end itemize
+
+@subsection = Serial Driver Functioning Overview
+
+Figure 5 is an attempt of showing how a Termios driven serial driver works : 
+
+@itemize @bullet
+
+@item the application programmer uses standard C library call (printf,
+scanf, read, write, etc.),
+
+@item C library (in fact that's Cygnus Newlib) calls RTEMS procedure: glue
+is made in newlib*.c files which can be found under
+$RTEMS_ROOT/c/src/lib/libc directory,
+
+@item Glue code calls your serial driver entry routines. 
+
+@end itemize
+
+@subsection = Polled I/O
+
+You have to point Termios out which functions are used for simple
+character input/output: 
+
+
+Function
+
+Description
+
+@example
+int pollWrite (int minor, const char *buf, int len) 
+
+for (i=0; i<len; i++) {
+     put buf[i] into the UART channel minor
+     wait for the character to be transmitted
+     on the serial line
+}
+int pollread(int minor)
+@end example
+
+wait for a character to be available in the UART channel minor, then return it.
+
+@subsection = Interrupted I/O
+
+The UART generally generates interrupts when it is ready to accept or to
+emit a number of characters. In this mode, the interrupt subroutine is the
+core of the driver: 
+
+
+Function
+
+Description
+
+@example
+rtems_isr InterruptHandler (rtems_vector_number v)
+@end example
+
+check whether there was an error
+
+if some characters were received: 
+   ask Termios to put them on his input buffer
+
+if some characters have been transmitted (i.e. the UART output buffer is empty)
+   tell TERMIOS that the characters have been
+   transmitted. The TERMIOS routine will call
+   the InterruptWrite function with the number
+   of characters not transmitted yet if it is
+   not zero.
+
+@example
+static int InterruptWrite(int minor, const char *buf, int len)
+@end example
+
+you have to put the n first buf characters in the UART channel minor
+buffer (n is the UART channel size, n=1 on the MC68640). Generally, an
+interrupt is raised after these n characters being transmitted. So you may
+have to enable the UART interrupts after having put the characters in the
+UART. 
+
+
+Figure 5: general TERMIOS driven serial driver functioning
+
+@subsection = Initialization
+
+The driver initialization is called once during RTEMS initialization
+process. 
+
+The console_initialize function has to : 
+
+@itemize @bullet
+
+@item initialize Termios support: call rtems_termios_initialize(),
+
+@item initialize your integrated processor's UART: the operation is
+normally described in your user's manual and you must follow these
+instructions but it usually consists in: 
+
+@item reinitialize the UART channels,
+
+@item set the channels configuration to Termios default one, i.e.: 9600
+bauds, no parity, 1 stop bit, 8 bits per character,
+
+@item register your console interrupt routine to RTEMS: 
+
+@example
+	rtems_interrupt_catch (InterruptHandler,CONSOLE_VECTOR,&old_handler);
+@end example
+
+@item enable the UART channels,
+
+@item register your device name: in order to use the console (i.e. being
+able to do printf/scanf on stdin, stdout, and stderr), you have to
+register the "/dev/console" device: 
+
+@example
+rtems_io_register_name ("dev/console", major, i);
+@end example
+
+@end itemize
+
+@subsection = Opening a serial device
+
+The console device is opened during RTEMS initialization but the
+console_open function is called when a new device is opened. For instance,
+if you register the "/dev/tty1" device for the UART channel 2, the
+console_open will be called with a fopen("/dev/t ty", mode) in your
+application. 
+
+The console_open function has to inform Termios of your low-level function
+for serial line support; the "callbacks". 
+
+The gen68340 BSP defines two kinds of callbacks: 
+
+@itemize @bullet
+
+@item functions to use with polled input/output,
+
+@item functions to use with interrupted input/output. 
+
+@end itemize
+
+@subsubsection = Polled I/O
+
+You have to point Termios out which functions are used for simple
+character input/output, i.e. pointers to pollWrite and pollRead functions
+defined in 8.4.1. 
+
+@subsubsection = Interrupted I/O
+
+Driver functioning is quite different in this mode. You can see there's no
+read function passed to Termios. Indeed a console_read call returns the
+content of Termios input buffer. This buffer is filled in the driver
+interrupt subroutine (cf. 8.4.2). 
+
+But you actually have to provide a pointer to the InterruptWrite function. 
+
+@subsection = Closing a serial device
+
+The driver entry point is: console_close. 
+
+You just have to notify Termios that the serial device was closed, with a
+call to rtems_termios_close. 
+
+@subsection = Reading characters from the serial device
+
+The driver entry point is: console_read. 
+
+You just have to return the content of the Termios input buffer. 
+
+Call rtems_termios_read. 
+
+@subsection = Writing characters to the serial device
+
+The driver entry point is: console_write. 
+
+You just have to add the characters at the end of the Termios output
+buffer. 
+
+Call rtems_termios_write. 
+
+@subsection = Changing serial line parameters
+
+The driver entry point is: console_control. 
+
+The application write is able to control the serial line configuration
+with Termios calls (such as the ioctl command, see Termios man page for
+more details). If you want to support dynamic configuration, you have to
+write the console_control piece of code . Look at the gen68340 BSP for an
+example of how it is done. Basically ioctl commands call console_control
+with the serial line configuration in a Termios structure. You just have
+to reinitialize the UART with the correct settings. 
+
diff --git a/doc/bsp_howto/init.t b/doc/bsp_howto/init.t
new file mode 100644
index 0000000000..1da0eec474
--- /dev/null
+++ b/doc/bsp_howto/init.t
@@ -0,0 +1,167 @@
+@chapter = The Initialization Code
+
+@subsection = Introduction
+
+The initialization code is the first piece of code executed when there's a
+reset/reboot. It aims at initializing the main functions of the board. As
+an introduction I advise you to give a look to the gen68340 BSP
+initialization code, which is split onto t wo directories: 
+
+@itemize @bullet
+
+@item $BSP340_ROOT/start340/: assembly language code which contains early
+initialization routines,
+
+@item $BSP340_ROOT/startup/: C code with higher level routines (RTEMS
+initialization related). 
+
+@end itemize
+
+@subsection = Board Initialization
+
+You'll find two files under the $BSP340_ROOT/start340/ directory, open
+rtemsfor340only.s which holds initialization code for a MC68340 board only
+and is simpler. 
+
+@subsection = The Interrupts Vector Table
+
+After the entry label starts a code section in which some room is
+allocated for the table of interrupts vectors. They are assigned to the
+address of the __uhoh label. 
+
+At __uhoh label you can find the default interrupt handler routine. This
+routine is only called when an unexpected interrupts is raised. You can
+add your own routine there (in that case there's a call to a routine -
+$BSP_ROOT/startup/dumpanic.c - that pri nts which address caused the
+interrupt and the contents of the registers, stack...), but this should
+not return. 
+
+@subsection = Chip Select Initialization
+
+When the microprocessor accesses a memory area, address decoding is
+handled by an address decoder (!), so that the microprocessor knows which
+memory chip to access. 
+
+Figure 4 : address decoding
+
+You have to program your Chip Select registers in order that they match
+the linkcmds settings. In this BSP ROM and RAM addresses can be found in
+both the linkcmds and initialization code, but this is not a great way to
+do, better use some shared variables . 
+
+@subsection = Integrated processor registers initialization
+
+There are always some specific integrated processor registers
+initialization to do. Integrated processors' user manuals often detail
+them. 
+
+@subsection = Data section recopy
+
+The next initialization part can be found in
+$BSP340_ROOT/start340/init68340.c. First the Interrupt Vector Table is
+copied into RAM, then the data section recopy is initiated
+(_CopyDataClearBSSAndStart in $BSP340_ROOT/start340/startfor340only.s). 
+
+This code :
+
+@itemize @bullet
+
+@item copies the .data section from ROM to its location reserved in RAM
+(see 5.2 for more details about this copy),
+
+@item clear .bss section (all the non-initialized data will take value 0). 
+
+@end itemize
+
+Then control is passed to the RTEMS-specific initialization code. 
+
+@subsection = RTEMS-Specific Initialization
+
+@subsection = The RTEMS configuration table
+
+The RTEMS configuration table contains the maximum number of objects RTEMS
+can handle during the application (e.g. maximum number of tasks,
+semaphores, etc.). It's used to allocate the size for the RTEMS inner data
+structures. 
+
+The RTEMS configuration table is application dependant, which means that
+one has to provide one per application. It's usually an header file
+included in the main module of the application. 
+
+The BSP_Configuration label points on this table. 
+
+For more information on the RTEMS configuration table, refer to C user's
+guide, chapter 23 <insert a link here>. 
+
+@subsection = RTEMS initialization procedure
+
+The RTEMS initialization procedure is described in the 3rd chapter of the
+C user's manual <insert a link here>. Please read it carefully. 
+
+There are a few BSP specific functions called from the initialization
+manager. They can be found in the startup directory of the BSP. 
+
+
+
+File
+
+Function
+
+Note
+
+bspstart.c
+
+
+
+It starts the application.  It includes application, board, and monitor
+specific initialization and configuration. 
+
+bspstart.c
+
+bsp_pretasking_hook
+
+It starts libc support (needed to allocate some memory using C primitive
+malloc for example). Heap size must be passed in argument, this is the one
+which is defined in the linkcmds (cf. 5.) 
+
+bspstart.c
+
+bsp_start
+
+Here the user and application specific configuration table has been
+"loaded" so that BSP_Configuration is up to date. 
+
+You can make last modifications here, for instance reserve more room for
+the RTEMS Work Space, or adjust the heap size (you can for example use the
+memory left for the lone heap). 
+
+bspclean.c
+
+bsp_cleanup
+
+Return control to the monitor. 
+
+@subsection = Drivers initialization
+
+The Driver Address Table is part of the RTEMS configuration table. It
+defines RTEMS drivers entry points (initialization, open, close, read,
+write, and control). For more information about this table, check C User's
+manual chapter 21 section 6 <insert a l ink here>. 
+
+The RTEMS initialization procedure calls the initialization function for
+every driver defined in the RTEMS Configuration Table (this permits to add
+only the drivers needed by the application). 
+
+All these primitives have a major and a minor number as arguments: 
+
+@itemize @bullet
+
+@item the major number refers to the driver type,
+
+@item the minor number is used to control two peripherals with the same
+driver (for instance, we define only one major number for the serial
+driver, but two minor numbers for channel A and B if there are two
+channels in the UART). 
+
+@end itemize
+
diff --git a/doc/bsp_howto/intro.t b/doc/bsp_howto/intro.t
new file mode 100644
index 0000000000..8cbcdd63a1
--- /dev/null
+++ b/doc/bsp_howto/intro.t
@@ -0,0 +1,24 @@
+@chapter = Introduction
+
+Before reading this documentation, it is strongly advised to read the
+RTEMS Development Environment Guide to get acquainted with the RTEMS
+directory structure.  This document describes how to do a RTEMS Board
+Support Package, i.e. how to port RTEMS on a new target board. Discussions
+are provided for the following topics:
+
+@itemize @bullet
+
+@item RTEMS Board Support Packages organization,
+
+@item Makefiles and the linker command script,
+
+@item Board initialization code,
+
+@item Clock driver,
+
+@item Console driver,
+
+@item Timer driver.
+
+@end itemize
+
diff --git a/doc/bsp_howto/linkcmds.t b/doc/bsp_howto/linkcmds.t
new file mode 100644
index 0000000000..62fe323b80
--- /dev/null
+++ b/doc/bsp_howto/linkcmds.t
@@ -0,0 +1,344 @@
+@chapter = The Linkcmds
+
+@subsection = What is a "linkcmds" file?
+
+The linkcmds file is a script which is passed to the linker at linking
+time. It holds somewhat the board memory configuration. 
+
+@subsection = Image of an Executable
+
+A program destined to be embedded has some specificities. Embedded
+machines often mean average performances and small memory usage. 
+
+Two types of memories have to be distinguished: one is volatile but on
+read and write access (RAM), while the other is non-volatile but read only
+(ROM). Even though RAM and ROM can be found in every personal computer,
+one generally doesn't care about them , because a program is always put in
+RAM and is executed in RAM. That's a bit different in embedded
+development: the target will execute the program each time it's reboot or
+switched on, which means the program is stored in ROM. On the other hand,
+data pr ocessing occurs in RAM. 
+
+
+
+That leads us to the structure of an embedded program: it's roughly made
+of sections, for instance for the Motorola 68k family of microprocessors : 
+
+@itemize @bullet
+
+@item the code section (aka ".txt" section): it holds the program's main
+code, so that it doesn't have to be modified. It's placed in ROM. 
+
+@item the non-initialized data section (aka ".bss" section): it holds non
+initialized variables of the program. It can stay in RAM. 
+
+@item the initialized data section (aka ".data" section): it holds the
+program data which are to be modified during the program's life, which
+means they have to be in RAM. On another hand, these variables must be set
+to predefined values, which have to be
+ stored in ROM... 
+
+@end itemize
+
+That brings us up to the notion of the image of an executable: it consists
+in the set of the program sections. 
+
+
+
+As a program executable has many sections (note that the user can define
+his own, and that compilers define theirs without any notice), one has to
+state in which type of memory (RAM or ROM) the sections will be arranged.
+For instance, a program compiled f or a Personal Computer will see all the
+sections to go to RAM, while a program destined to be embedded will see
+some of his sections going into the ROM. 
+
+
+
+The (section, area of memory) connection is made at linking time. One have
+to make the linker know the different sections location once they're in
+memory. 
+
+
+Figure 2 : sections location in memory 
+
+The GNU linker has a command language to specify the image format.  Let's
+have a look to the "gen68340"  BSP linkcmds, which can be found at
+$BSP340_ROOT/startup/linkcmds. 
+
+
+@example
+OUTPUT_FORMAT(coff-m68k) 
+
+RamSize = DEFINED(RamSize) ? RamSize : 4M;
+HeapSize = DEFINED(HeapSize) ? HeapSize : 0x10000;
+StackSize = DEFINED(StackSize) ? StackSize : 0x1000;
+
+MEMORY {
+          ram : ORIGIN = 0x10000000, LENGTH = 4M
+          rom : ORIGIN = 0x01000000, LENGTH = 4M
+}
+
+ETHERNET_ADDRESS = DEFINED(ETHERNET_ADDRESS) ? ETHERNET_ADDRESS : 0xDEAD12;
+
+/*
+ * Load objects
+ */
+SECTIONS {
+	/*
+	 * Hardware variations
+	 */
+	_RamSize = RamSize;
+	__RamSize = RamSize;
+
+        /*
+         * Boot PROM
+         */
+        rom : {
+                _RomBase = .;
+                __RomBase = .;
+        } >rom
+
+        /*
+         * Dynamic RAM
+         */
+        ram : {
+                _RamBase = .;
+                __RamBase = .;
+        } >ram
+
+        /*
+         * Text, data and bss segments
+         */
+        .text : {
+                CREATE_OBJECT_SYMBOLS
+
+
+                *(.text)
+
+
+                . = ALIGN (16);
+
+
+		/*
+		 * C++ constructors
+		 */
+		__CTOR_LIST__ = .;
+               [......]
+		__DTOR_END__ = .;
+
+                etext = .;
+                _etext = .;
+        } >rom 
+
+	.eh_fram : {
+		. = ALIGN (16);
+		*(.eh_fram)
+	} >ram
+
+	.gcc_exc : {
+		. = ALIGN (16);
+		*(.gcc_exc)
+	} >ram
+
+        dpram : {
+                m340 = .;
+                _m340 = .;
+                . += (8 * 1024);
+        } >ram
+
+        .data : {
+                copy_start = .;
+                *(.data)
+
+                . = ALIGN (16);
+                _edata = .;
+                copy_end = .;
+        } >ram
+
+        .bss : {
+                M68Kvec = .;
+                _M68Kvec = .;
+                . += (256 * 4);
+
+
+                clear_start = .;
+
+                *(.bss)
+
+                *(COMMON)
+
+                . = ALIGN (16);
+                _end = .;
+
+                _HeapStart = .;
+                __HeapStart = .;
+                . += HeapSize;  
+                . += StackSize;
+                . = ALIGN (16);
+                stack_init = .;
+
+                clear_end = .;
+
+                _WorkspaceBase = .;
+                __WorkspaceBase = .;
+
+
+
+        } >ram
+}
+@end example
+
+executable format is COFF
+
+your default board RAM size here. 
+
+Note that it's possible to change it by passing an argument to ld
+
+the default heap size: beware! the heap must be large enough to contain: 
+
+@itemize @bullet
+
+@item your program's static allocations
+
+@item your program's dynamic allocations
+
+@item ALL YOUR PROCESS'S STACK
+
+@end itemize
+
+Having a tight heap size is somewhat difficult and many tries are needed
+if you want to save the memory usage. 
+
+
+The Stacksize should only be large enough to hold the stack in the
+initialization sequence. Then the tasks stacks will be allocated in the
+Heap. 
+
+Start address of RAM and its length. 
+
+The start address must be a valid address. Most often RAM is assigned to a
+given chip of memory on the board, and a Chip Select is assigned to this
+chip with an address (see the Initialization sequence chapter).
+
+
+Start address of ROM and its length.  Same remarks as above. 
+
+this is for the network driver (see KA9Q documentation for more details) 
+
+define where the sections should go: 
+
+define some variables that the user code can access.
+
+set the RomBase variable to the start of the ROM.
+
+set the RamBase variable to the start of the RAM.
+
+states that a symbol shall be created for each object (.o)
+
+insert the .text sections of every object
+
+go to a frontier of 16 bytes (just keep it as is)
+
+reserve some place for C++ constructors and destructors.
+
+just keep it as is (or see CROSSGCC mailing-list FAQ for more details)
+
+declares where the .txt section ends.
+
+the .txt section goes in ROM!
+
+this section is created by GCC
+
+put it in RAM.
+
+this section is created by GCC
+
+put it in RAM
+
+room for peripherals
+
+needs 8 Kbytes
+put it in RAM
+
+the initialized data section
+
+put all the objects' .data sections in the .data section of the image
+
+.data section goes in RAM
+
+the non initialized data section
+
+
+reserve some room for the Table of Vector Interrupts (256 vectors of 4 bytes)
+
+pointer to the start of the non initialized data
+
+put all the objects .bss sections in the .bss section of the image
+
+put all the non initialized data, which are not in .bss sections
+
+Heap start
+
+reserve some room for the heap
+
+reserve some room for the stack
+
+top of the stack (remember the stack grows with addresses going down)
+
+end of the non initialized data
+
+start of the RTEMS Workspace (holds RTEMS configuration table and a few
+other things, its size is calculated by RTEMS according to your
+configuration, <INSERT A LINK HERE>) 
+
+the resulting .bss section goes in RAM
+
+
+Now there's a problem with the initialized data: the .data section has to
+be in RAM as these data are to be modified during the program execution.
+But how will they be initialized at boot time? 
+
+
+
+One should be aware of the running executable image and the file to
+download to the target image being different! In practice, the initialized
+data section is copied at the end of the code section (i.e. in ROM) when
+building a PROM image. The GNU tool obj copy can be used for this purpose. 
+
+
+
+Figure 3 : copy of the initialized data section to build a PROM image
+
+
+
+This process is made after the linking time, and you can find an example
+of how it is done in $RTEMS_ROOT/make/custom/gen68340.cfg : 
+
+@example
+# make a prom image
+m68k-rtems-objcopy \
+--adjust-section-vma .data= \
+
+`m68k-rtems-objdump --section-headers \
+$(basename $@).exe \
+| awk '[...]` \
+$(basename $@).exe
+@end example
+
+use the target objcopy
+
+we want to move the start of the section .data
+
+in the resulting image
+
+the address is given by extracting the address of the end of the .text
+section (i.e. in ROM) with an awk script (don't care about it) 
+
+process the image which have just been linked
+
+
+
+The board initialization code (cf. 6) will copy the initialized data
+initial values (which are stored in ROM) to their reserved location in
+RAM. 
+
diff --git a/doc/bsp_howto/makefiles.t b/doc/bsp_howto/makefiles.t
new file mode 100644
index 0000000000..db714b9a04
--- /dev/null
+++ b/doc/bsp_howto/makefiles.t
@@ -0,0 +1,142 @@
+@chapter = The Makefiles
+
+@subsection = Makefiles Used During The BSP Building Process
+
+There's a makefile template in each directory of a BSP. They are called
+"makefile.in" and are processed when building RTEMS for a given BSP. One
+should specify the needed files and directories before the building
+process. 
+
+@itemize @bullet
+
+@item the makefile.in at the BSP root specifies which folders have to be
+included. For instance,
+
+@item We only build the ka9q device driver if HAS_KA9Q was defined
+
+@example
+KA9Q_DRIVER_yes_V = network
+KA9Q_DRIVER = $(KA9Q_DRIVER_$(HAS_KA9Q)_V) 
+
+[...]
+
+SUB_DIRS=include start340 startup clock console timer $(KA9Q_DRIVER) wrapup
+@end example
+
+states that all the directories have to be processed, except for the
+network directory which is included only if the user asked for it when
+building RTEMS. 
+
+@item the makefile.in in each driver directory. It lists the files to be
+included in the driver, so don't forget to add the reference to a new file
+in the makefile.in of a given driver when it is created! 
+
+@end itemize
+
+
+Rem : the makefile.in files are ONLY processed during the configure
+process of a RTEMS build. It means that, when you're working on the design
+of your BSP, and that you're adding a file to a folder and to the
+corresponding makefile.in, it will not be take n into account! You have to
+run configure again or modify the makefile (result of the makefile.in
+process, usually in your <the RTEMS build
+directory>/c/src/lib/libbsp/<your BSP family>/<your BSP>/<your driver>
+directory) by hand. 
+
+@subsection = Makefiles Used Both During The BSP Design and its Use
+
+A BSP must go with his configuration file. The configuration files can be
+found under $RTEMS_ROOT/c/make/custom. The configuration file is taken
+into account when building one's application using the template makefiles
+($RTEMS_ROOT/c/make/templates), whic h is strongly advised. There are
+templates for calling recursively the makefiles in the directories beneath
+the current one, building a library or an executable.
+
+Let's see what it looks like :
+
+@example
+RTEMS_CPU=m68k
+
+TARGET_ARCH=o-gen68340
+RTEMS_CPU_MODEL=mcpu32
+
+include $(RTEMS_ROOT)/make/custom/default.cfg
+
+RTEMS_BSP_FAMILY=gen68340
+
+## Target compiler config file, if any
+CONFIG.$(TARGET_ARCH).CC = $(RTEMS_ROOT)/make/compilers/gcc-target-default.cfg
+
+RTEMS_BSP=gen68340
+
+CPU_CFLAGS = -mcpu32
+
+# optimize flag: 
+CFLAGS_OPTIMIZE_V=-O4 -fomit-frame-pointer
+
+# Override default start file
+START_BASE=start340
+
+[...]
+
+ifeq ($(RTEMS_USE_GCC272),yes)
+[...]
+else
+
+define make-exe
+	$(CC) $(CFLAGS) $(CFLAGS_LD) -o $(basename $@).exe $(LINK_OBJS)
+	$(NM) -g -n $(basename $@).exe > $(basename $@).num
+	$(SIZE) $(basename $@).exe
+endif
+@end example
+
+the main board CPU family
+
+directory where you want the objects to go
+
+the main board CPU name for GCC
+
+include standard definitions
+
+bsp directory used during the build process 
+
+cross-compiler options
+
+
+
+
+the name of your bsp directory
+
+CPU flag to pass to GCC
+
+optimisation flag to pass to GCC
+
+
+name of your BSP function to be called immediately after reboot
+
+
+
+if an older version of GCC is used...
+
+
+
+this macro is used in template makefiles to build the final executable.
+Any other commands to follow, just as using objcopy to build a PROM image
+or converting the executable to binary. 
+
+Figure 1 : custom file for gen68340 BSP ($RTEMS_ROOT/make/custom/gen68340.cfg)
+
+
+
+What you have to do:
+
+@itemize @bullet
+
+@item copy any .cfg file to <your BSP>.cfg
+
+@item modify RTEMS_CPU, TARGET_ARCH, RTEMS_CPU_MODEL, RTEMS_BSP_FAMILY,
+RTEMS_BSP, CPU_CFLAGS, START_BASE accordingly. 
+
+@end itemize
+
+
diff --git a/doc/bsp_howto/target.t b/doc/bsp_howto/target.t
new file mode 100644
index 0000000000..5248390cf0
--- /dev/null
+++ b/doc/bsp_howto/target.t
@@ -0,0 +1,34 @@
+@chapter = Target Dependent and Board Dependent Files
+
+RTEMS divides board dependencies into two parts :
+
+@itemize @bullet
+
+@item the CPU dependant code : it provides basics calls to the kernel,
+just as the context switch or the interrupt subroutine implementations.
+Sources for the supported families of processors can be found in
+$RTEMS_ROOT/c/src/exec/score/cpu. A good starti ng point for a new family
+of processors is the no_cpu directory, which holds both prototypes and
+descriptions of each needed CPU dependant function. 
+
+@item the board dependant code : it includes support for a given board,
+such as the board initialization code and drivers for the various devices:
+clock, UARTs, ethernet board, etc.
+
+
+@end itemize
+
+Porting RTEMS on a new board should raise two questions :
+
+@itemize @bullet
+
+@item is the main board CPU supported ?
+
+@item does a BSP for a similar board exists ?
+
+@end itemize
+
+If the main board CPU is supported, you will only have do write the Board
+Support Package. Otherwise you'll have to write both CPU dependant code
+and the BSP. One should always start writing a BSP from a similar one. 
+
diff --git a/doc/bsp_howto/timer.t b/doc/bsp_howto/timer.t
new file mode 100644
index 0000000000..f8f96b17c2
--- /dev/null
+++ b/doc/bsp_howto/timer.t
@@ -0,0 +1,66 @@
+@chapter = Timer Driver
+
+You can program the timer driver for your own needs, but here are two uses
+of it: 
+
+@subsection = UART'S FIFO Full Mode
+
+The gen68340 BSP is an example of the use of the timer to support the UART
+input FIFO full mode (FIFO means First In First Out and roughly means
+buffer). This mode consists in the UART raising an interrupt when n
+characters have been received (n is the UA RT's FIFO length). It results
+in a lower interrupt processing time, but the problem is that a scanf
+primitive will block on a receipt of less than n characters. The solution
+is to set a timer that will check whether there are some characters
+waiting in th e UART's input FIFO. The delay time has to be set carefully
+otherwise high rates will be broken: 
+
+@itemize @bullet
+
+@item if no character was received last time the interrupt subroutine was
+entered, set a long delay,
+
+@item otherwise set the delay to the delay needed for n characters
+receipt. 
+
+@end itemize
+
+@subsection = Measuring RTEMS Primitives Time
+
+RTEMS Timing Test Suite needs a timer support. You have to provide two
+primitives: 
+
+
+
+Function
+
+Description
+
+@example
+void Timer_initialize (void)
+@end example
+
+Initialize the timer to be a counter to the microsecond.
+
+@example
+int Read_timer (void)
+@end example
+
+Returns the number of microseconds elapsed since the last call to
+Timer_initialize. 
+
+@example
+rtems_status_code Empty_function (void)
+
+return RTEMS_SUCCESSFUL;
+@end example
+
+@example
+void Set_find_average_overhead (rtems_boolean find_flag)
+@end example
+
+DOES NOTHING ????????????????????????????????????????????????????????????????????????????????????????????????????
+
+		
+
+