Patch rtemsdoc-4.5.0-rc-0.diff from Ralf Corsepius <corsepiu@faw.uni-ulm.de>

which contains the bulk of converting the documentation tree to automake
and GNU conventions.  Comments follow:

This is the automake port of rtemsdoc.

To apply:

cvs co rtemsdoc
cd rtemsdoc
sh cvs-rm.sh
patch -p0 < rtemsdoc-4.5.0-rc-0.diff
sh cvs-add.sh

[Attention: cvs-rm.sh and cvs-add.sh directly modify cvs]

Known bugs:
1) src2html is not supported (yet? - Is this supposed to work?)
2) all *.pdf images now are generated on-the-fly, but not yet deleted
during "make distclean"
3) All supplements, including the templated ones, get build and
installed.
4) Building outside of the source tree is completely untested and very
likely does not work.
5) Make [ps|pdf] are not (yet) supported, make [dvi|info] are supported
by automake's default texinfo rules.

Fixing 2, 3 and 5 is almost trivial and needs to be done.
4) is a matter of testing and tool-properties, for now it is simply
untested.



General issues:
* gif vs jpg vs png. I would recommend to replace all images with pngs
  to avoid potential copyright issues (gif) or lack in quality (jpg, jpg
  is good for real world photographs, but extremely poor on artificial
  images, graphs).
* pdf images do net get placed correctly in pdf-documents.
* texinfo: We now use a local copy of texinfo-4.0's texinfo.tex in
  texinfo/texinfo.tex for generating infos. However pdftex's system-wide
  texinfo.tex and pdftexinfo.tex are used for generating *.dvi, *.ps, *.pdf.
* .cvsignore files still missing.
* I have renamed the supplements filename not to use c_<supplement>,
  because automake seems to have problems with it.

Notes:
* Again, I recommend not to put any generated files into CVS. Here, this
  comprises some *texi, all *.pdf and many *.html pages. Ie. I recommend
  to run make maintainer-clean before checking in any files.

* To get building started, this should be sufficient:
  ./bootstrap
  ./configure
  cd tools; make; cd ..
  make info

* To make a public tarball:
  [cvs co ; ./bootstrap]
  ./configure
  cd tools; make; cd ..
  make info
  [make clean]
  make dist
=> This generates a rtems-<version>.tar.gz in the toplevel directory.
=> Building the tools only is required after a "cvs co", but not in a
   distribution tarball.

3 files changed, 460 insertions, 152 deletions

diff --git a/doc/bsp_howto/Makefile b/doc/bsp_howto/Makefile
deleted file mode 100644
index 0e12e674b3..0000000000
--- a/doc/bsp_howto/Makefile
+++ /dev/null
@@ -1,152 +0,0 @@
-#
-#  COPYRIGHT (c) 1988-1999.
-#  On-Line Applications Research Corporation (OAR).
-#  All rights reserved.
-#
-#  $Id$
-#
-
-PROJECT=bsp_howto
-
-include ../Make.config
-
-all: html info ps pdf
-
-dirs:
-	$(make-dirs)
-
-COMMON_FILES=../common/cpright.texi ../common/setup.texi
-
-GENERATED_FILES= \
-    intro.texi target.texi makefiles.texi linkcmds.texi support.texi \
-    adaintr.texi init.texi console.texi clock.texi timer.texi rtc.texi \
-    nvmem.texi network.texi shmsupp.texi analog.texi discrete.texi
-
-FILES=$(PROJECT).texi $(GENERATED_FILES)
-
-INFOFILES=$(wildcard $(PROJECT) $(PROJECT)-*)
-
-info: dirs $(PROJECT)
-	#cp $(wildcard $(PROJECT) $(PROJECT)-*) $(INFO_INSTALL)
-	# cp $(PROJECT) $(INFO_INSTALL)
-
-$(PROJECT): $(FILES)
-	$(MAKEINFO) $(PROJECT).texi
-
-dvi: dirs $(PROJECT).dvi
-ps: dirs $(PROJECT).ps
-pdf: dirs $(PROJECT).pdf
-	
-$(PROJECT).pdf: $(FILES)
-	$(TEXI2PDF) $(PROJECT).texi
-	cp $(PROJECT).pdf $(WWW_INSTALL)/$(PROJECT)
-	
-$(PROJECT).ps: $(PROJECT).dvi
-	dvips -o $(PROJECT).ps $(PROJECT).dvi
-	cp $(PROJECT).ps $(WWW_INSTALL)/$(PROJECT)
-
-$(PROJECT).dvi: $(FILES)
-	$(TEXI2DVI) $(PROJECT).texi
-	cp $(PROJECT).dvi $(WWW_INSTALL)/$(PROJECT)
-
-html: dirs $(FILES)
-	-mkdir -p $(WWW_INSTALL)/$(PROJECT)
-	$(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \
- 	    $(PROJECT).texi
-
-clean:
-	rm -f *.o $(PROG) *.txt core $(PROJECT).pdf
-	rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE)
-	rm -f $(PROJECT) $(PROJECT)-* $(GENERATED_FILES)
-	rm -f *.fixed _* network.t
-
-#
-#  Grab the chapter on writing a network device driver.
-#
-network.t: 
-	ln -s ../networking/driver.t  network.t
-
-
-#
-#  Process Automatically Generated Files
-#
-
-intro.texi: intro.t Makefile
-	$(BMENU) -p "Top" \
-	    -u "Top" \
-	    -n "Target Dependent Files" ${*}.t
-
-target.texi: target.t Makefile
-	$(BMENU) -p "Introduction" \
-	    -u "Top" \
-	    -n "Makefiles" ${*}.t
-
-makefiles.texi: makefiles.t Makefile
-	$(BMENU) -p "Target Dependent Files Board Support Package Structure" \
-	    -u "Top" \
-	    -n "Linker Script" ${*}.t
-
-linkcmds.texi: linkcmds.t Makefile
-	$(BMENU) -p "Makefiles Creating a New BSP Make Customization File" \
-	    -u "Top" \
-	    -n "Ada95 Interrupt Support" ${*}.t
-
-adaintr.texi: adaintr.t Makefile
-	$(BMENU) -p "Linker Script Initialized Data" \
-	    -u "Top" \
-	    -n "Miscellaneous Support Files" ${*}.t
-
-support.texi: support.t Makefile
-	$(BMENU) -p "Ada95 Interrupt Support Version Requirements" \
-	    -u "Top" \
-	    -n "" ${*}.t
-
-init.texi: init.t Makefile
-	$(BMENU) -p "" \
-	    -u "Top" \
-	    -n "" ${*}.t
-
-console.texi: console.t Makefile
-	$(BMENU) -p "" \
-	    -u "Top" \
-	    -n "" ${*}.t
-
-clock.texi: clock.t Makefile
-	$(BMENU) -p "" \
-	    -u "Top" \
-	    -n "" ${*}.t
-
-timer.texi: timer.t Makefile
-	$(BMENU) -p "" \
-	    -u "Top" \
-	    -n "" ${*}.t
-
-rtc.texi: rtc.t Makefile
-	$(BMENU) -p "" \
-	    -u "Top" \
-	    -n "" ${*}.t
-
-nvmem.texi: nvmem.t Makefile
-	$(BMENU) -p "" \
-	    -u "Top" \
-	    -n "" ${*}.t
-
-network.texi: network.t Makefile
-	$(BMENU) -p "" \
-	    -u "Top" \
-	    -n "" ${*}.t
-
-shmsupp.texi: shmsupp.t Makefile
-	$(BMENU) -p "" \
-	    -u "Top" \
-	    -n "" ${*}.t
-
-analog.texi: analog.t Makefile
-	$(BMENU) -p "" \
-	    -u "Top" \
-	    -n "" ${*}.t
-
-discrete.texi: discrete.t Makefile
-	$(BMENU) -p "" \
-	    -u "Top" \
-	    -n "" ${*}.t
diff --git a/doc/bsp_howto/Makefile.am b/doc/bsp_howto/Makefile.am
new file mode 100644
index 0000000000..4657bbe873
--- /dev/null
+++ b/doc/bsp_howto/Makefile.am
@@ -0,0 +1,118 @@
+#
+#  COPYRIGHT (c) 1988-1999.
+#  On-Line Applications Research Corporation (OAR).
+#  All rights reserved.
+#
+#  $Id$
+#
+
+AUTOMAKE_OPTIONS = foreign
+
+PROJECT=bsp_howto
+
+include $(top_srcdir)/project.am
+
+COMMON_FILES=$(top_srcdir)/common/cpright.texi $(top_builddir)/common/setup.texi
+
+GENERATED_FILES= \
+    intro.texi target.texi makefiles.texi linkcmds.texi support.texi \
+    adaintr.texi init.texi console.texi clock.texi timer.texi rtc.texi \
+    nvmem.texi network.texi shmsupp.texi analog.texi discrete.texi
+
+FILES=
+
+info_TEXINFOS = bsp_howto.texi
+bsp_howto_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)   
+
+#
+#  Grab the chapter on writing a network device driver.
+#
+network.t: 
+	ln -s ../networking/driver.t  network.t
+
+
+#
+#  Process Automatically Generated Files
+#
+
+intro.texi: intro.t
+	$(BMENU) -p "Top" \
+	    -u "Top" \
+	    -n "Target Dependent Files" $<
+
+target.texi: target.t
+	$(BMENU) -p "Introduction" \
+	    -u "Top" \
+	    -n "Makefiles" $<
+
+makefiles.texi: makefiles.t
+	$(BMENU) -p "Target Dependent Files Board Support Package Structure" \
+	    -u "Top" \
+	    -n "Linker Script" $<
+
+linkcmds.texi: linkcmds.t
+	$(BMENU) -p "Makefiles Creating a New BSP Make Customization File" \
+	    -u "Top" \
+	    -n "Ada95 Interrupt Support" $<
+
+adaintr.texi: adaintr.t
+	$(BMENU) -p "Linker Script Initialized Data" \
+	    -u "Top" \
+	    -n "Miscellaneous Support Files" $<
+
+support.texi: support.t
+	$(BMENU) -p "Ada95 Interrupt Support Version Requirements" \
+	    -u "Top" \
+	    -n "" $<
+
+init.texi: init.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" $<
+
+console.texi: console.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" $<
+
+clock.texi: clock.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" $<
+
+timer.texi: timer.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" $<
+
+rtc.texi: rtc.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" $<
+
+nvmem.texi: nvmem.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" $<
+
+network.texi: network.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" $<
+
+shmsupp.texi: shmsupp.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" $<
+
+analog.texi: analog.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" $<
+
+discrete.texi: discrete.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" $<
+
+EXTRA_DIST = *.t
diff --git a/doc/bsp_howto/network.t b/doc/bsp_howto/network.t
new file mode 100644
index 0000000000..c2fa4866f6
--- /dev/null
+++ b/doc/bsp_howto/network.t
@@ -0,0 +1,342 @@
+@c
+@c  Written by Eric Norum
+@c
+@c  COPYRIGHT (c) 1988-1999.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@chapter Networking Driver
+
+@section Introduction
+
+This chapter is intended to provide an introduction to the
+procedure for writing RTEMS network device drivers.
+The example code is taken from the `Generic 68360' network device
+driver.  The source code for this driver is located in the
+@code{c/src/lib/libbsp/m68k/gen68360/network} directory in the RTEMS
+source code distribution.  Having a copy of this driver at
+hand when reading the following notes will help significantly.
+
+@section Learn about the network device 
+
+Before starting to write the network driver become completely
+familiar with the programmer's view of the device.
+The following points list some of the details of the
+device that must be understood before a driver can be written.
+
+@itemize @bullet
+
+@item Does the device use DMA to transfer packets to and from
+memory or does the processor have to
+copy packets to and from memory on the device?
+
+@item If the device uses DMA, is it capable of forming a single
+outgoing packet from multiple fragments scattered in separate
+memory buffers?
+
+@item If the device uses DMA, is it capable of chaining multiple
+outgoing packets, or does each outgoing packet require
+intervention by the driver?
+
+@item Does the device automatically pad short frames to the minimum
+64 bytes or does the driver have to supply the padding?
+
+@item Does the device automatically retry a transmission on detection
+of a collision?
+
+@item If the device uses DMA, is it capable of buffering multiple
+packets to memory, or does the receiver have to be restarted
+after the arrival of each packet?
+
+@item How are packets that are too short, too long, or received with
+CRC errors handled?  Does the device automatically continue
+reception or does the driver have to intervene?
+
+@item How is the device Ethernet address set?  How is the device
+programmed to accept or reject broadcast and multicast packets?
+
+@item What interrupts does the device generate?  Does it generate an
+interrupt for each incoming packet, or only for packets received
+without error?  Does it generate an interrupt for each packet
+transmitted, or only when the transmit queue is empty?  What
+happens when a transmit error is detected?
+
+@end itemize
+
+In addition, some controllers have specific questions regarding 
+board specific configuration.  For example, the SONIC Ethernet
+controller has a very configurable data bus interface.  It can
+even be configured for sixteen and thirty-two bit data buses.  This
+type of information should be obtained from the board vendor.
+
+@section Understand the network scheduling conventions
+
+When writing code for the driver transmit and receive tasks,
+take care to follow the network scheduling conventions.  All tasks
+which are associated with networking share various
+data structures and resources.  To ensure the consistency
+of these structures the tasks
+execute only when they hold the network semaphore (@code{rtems_bsdnet_semaphore}).
+The transmit and receive tasks must abide by this protocol.  Be very
+careful to avoid `deadly embraces' with the other network tasks.
+A number of routines are provided to make it easier for the network
+driver code to conform to the network task scheduling conventions.
+
+@itemize @bullet
+
+@item @code{void rtems_bsdnet_semaphore_release(void)}
+
+This function releases the network semaphore.
+The network driver tasks must call this function immediately before
+making any blocking RTEMS request.
+
+@item @code{void rtems_bsdnet_semaphore_obtain(void)}
+
+This function obtains the network semaphore.
+If a network driver task has released the network semaphore to allow other
+network-related tasks to run while the task blocks, then this function must 
+be called to reobtain the semaphore immediately after the return from the
+blocking RTEMS request.
+
+@item @code{rtems_bsdnet_event_receive(rtems_event_set, rtems_option, rtems_interval, rtems_event_set *)}
+The network driver task should call this function when it wishes to wait
+for an event.  This function releases the network semaphore,
+calls @code{rtems_event_receive} to wait for the specified event
+or events and reobtains the semaphore.
+The value returned is the value returned by the @code{rtems_event_receive}.
+
+@end itemize
+
+@section Network Driver Makefile
+
+Network drivers are considered part of the BSD network package and as such
+are to be compiled with the appropriate flags.  This can be accomplished by 
+adding @code{-D__INSIDE_RTEMS_BSD_TCPIP_STACK__} to the @code{command line}.
+If the driver is inside the RTEMS source tree or is built using the
+RTEMS application Makefiles, then adding the following line accomplishes
+this:
+
+@example
+DEFINES += -D__INSIDE_RTEMS_BSD_TCPIP_STACK__
+@end example
+
+This is equivalent to the following list of definitions.  Early versions
+of the RTEMS BSD network stack required that all of these be defined.
+
+@example
+-D_COMPILING_BSD_KERNEL_ -DKERNEL -DINET -DNFS \
+    -DDIAGNOSTIC -DBOOTP_COMPAT
+@end example
+
+Defining these macros tells the network header files that the driver
+is to be compiled with extended visibility into the network stack.  This
+is in sharp contrast to applications that simply use the network stack.
+Applications do not require this level of visibility and should stick
+to the portable application level API.
+
+As a direct result of being logically internal to the network stack,
+network drivers use the BSD memory allocation routines   This means,
+for example, that malloc takes three arguments.  See the SONIC
+device driver (@code{c/src/lib/libchip/network/sonic.c}) for an example
+of this.  Because of this, network drivers should not include 
+@code{<stdlib.h>}.  Doing so will result in conflicting definitions
+of @code{malloc()}.
+
+@b{Application level} code including network servers such as the FTP
+daemon are @b{not} part of the BSD kernel network code and should not be
+compiled with the BSD network flags.  They should include
+@code{<stdlib.h>} and not define the network stack visibility
+macros.
+
+@section Write the Driver Attach Function
+
+The driver attach function is responsible for configuring the driver
+and making the connection between the network stack
+and the driver.
+
+Driver attach functions take a pointer to an
+@code{rtems_bsdnet_ifconfig} structure as their only argument.
+and set the driver parameters based on the
+values in this structure.  If an entry in the configuration
+structure is zero the attach function chooses an
+appropriate default value for that parameter.
+
+
+The driver should then set up several fields in the ifnet structure
+in the device-dependent data structure supplied and maintained by the driver:
+
+@table @code
+@item ifp->if_softc 
+Pointer to the device-dependent data.  The first entry
+in the device-dependent data structure must be an @code{arpcom}
+structure.
+
+@item ifp->if_name
+The name of the device.  The network stack uses this string
+and the device number for device name lookups.  The device name should
+be obtained from the @code{name} entry in the configuration structure.
+
+@item ifp->if_unit
+The device number.  The network stack uses this number and the
+device name for device name lookups.  For example, if
+@code{ifp->if_name} is @samp{scc} and @code{ifp->if_unit} is @samp{1},
+the full device name would be @samp{scc1}.  The unit number should be
+obtained from the `name' entry in the configuration structure.
+
+@item ifp->if_mtu
+The maximum transmission unit for the device.  For Ethernet
+devices this value should almost always be 1500.
+
+@item ifp->if_flags
+The device flags.  Ethernet devices should set the flags
+to @code{IFF_BROADCAST|IFF_SIMPLEX}, indicating that the
+device can broadcast packets to multiple destinations
+and does not receive and transmit at the same time.
+
+@item ifp->if_snd.ifq_maxlen
+The maximum length of the queue of packets waiting to be
+sent to the driver.  This is normally set to @code{ifqmaxlen}.
+
+@item ifp->if_init
+The address of the driver initialization function.
+
+@item ifp->if_start
+The address of the driver start function.
+
+@item ifp->if_ioctl
+The address of the driver ioctl function.
+
+@item ifp->if_output
+The address of the output function.  Ethernet devices
+should set this to @code{ether_output}.
+@end table
+
+RTEMS provides a function to parse the driver name in the
+configuration structure into a device name and unit number.
+
+@example
+int rtems_bsdnet_parse_driver_name (
+  const struct rtems_bsdnet_ifconfig *config,
+  char **namep
+);
+@end example
+
+The function takes two arguments; a pointer to the configuration
+structure and a pointer to a pointer to a character.  The function
+parses the configuration name entry, allocates memory for the driver
+name, places the driver name in this memory, sets the second argument
+to point to the name and returns the unit number. 
+On error, a message is printed and -1 is returned.
+
+Once the attach function  has set up the above entries it must link the
+driver data structure onto the list of devices by
+calling @code{if_attach}.  Ethernet devices should then
+call @code{ether_ifattach}.  Both functions take a pointer to the
+device's @code{ifnet} structure as their only argument.
+
+The attach function should return a non-zero value to indicate that
+the driver has been successfully configured and attached.
+
+@section Write the Driver Start Function.
+This function is called each time the network stack wants to start the
+transmitter.  This occures whenever the network stack adds a packet
+to a device's send queue and the @code{IFF_OACTIVE} bit in the
+device's @code{if_flags} is not set.
+
+For many devices this function need only set the @code{IFF_OACTIVE} bit in the
+@code{if_flags} and send an event to the transmit task
+indicating that a packet is in the driver transmit queue.
+
+
+@section Write the Driver Initialization Function.
+
+This function should initialize the device, attach to interrupt handler, 
+and start the driver transmit and receive tasks.  The function
+
+@example
+rtems_id
+rtems_bsdnet_newproc (char *name,
+		      int stacksize,
+		      void(*entry)(void *),
+		      void *arg);
+@end example
+
+should be used to start the driver tasks.
+
+Note that the network stack may call the driver initialization function more
+than once.
+Make sure multiple versions of the receive and transmit tasks are not accidentally
+started.
+
+
+
+@section Write the Driver Transmit Task
+
+This task is reponsible for removing packets from the driver send queue and sending them to the device.  The task should block waiting for an event from the
+driver start function indicating that packets are waiting to be transmitted.
+When the transmit task has drained the driver send queue the task should clear
+the @code{IFF_OACTIVE} bit in @code{if_flags} and block until another outgoing
+packet is queued.
+
+
+@section Write the Driver Receive Task
+This task should block until a packet arrives from the device.  If the
+device is an Ethernet interface the function @code{ether_input} should be called
+to forward the packet to the network stack.   The arguments to @code{ether_input}
+are a pointer to the interface data structure, a pointer to the ethernet
+header and a pointer to an mbuf containing the packet itself.
+
+
+
+
+@section Write the Driver Interrupt Handler
+A typical interrupt handler will do nothing more than the hardware
+manipulation required to acknowledge the interrupt and send an RTEMS event
+to wake up the driver receive or transmit task waiting for the event.
+Network interface interrupt handlers must not make any calls to other
+network routines.
+
+
+
+@section Write the Driver IOCTL Function
+This function handles ioctl requests directed at the device.  The ioctl
+commands which must be handled are:
+
+@table @code
+@item SIOCGIFADDR
+@item SIOCSIFADDR
+If the device is an Ethernet interface these
+commands should be passed on to @code{ether_ioctl}.
+
+@item SIOCSIFFLAGS
+This command should be used to start or stop the device,
+depending on the state of the interface @code{IFF_UP} and
+@code{IFF_RUNNING} bits in @code{if_flags}:
+@table @code
+@item IFF_RUNNING
+Stop the device.
+
+@item IFF_UP
+Start the device.
+
+@item IFF_UP|IFF_RUNNING
+Stop then start the device.
+
+@item 0
+Do nothing.
+
+@end table
+@end table
+
+
+
+@section Write the Driver Statistic-Printing Function
+This function should print the values of any statistic/diagnostic
+counters the network driver may use.  The driver ioctl function should call
+the statistic-printing function when the ioctl command is
+@code{SIO_RTEMS_SHOW_STATS}.
+
+