Changeset bc950e87 – RTEMS Project

doc/bsp_howto/Makefile

-                      r06fee20
+                      rbc950e87
 $(PROJECT).dvi: $(FILES)
         $(TEXI2DVI) $(PROJECT).texi
         $(TEXI2DVI) $(PROJECT).texi
+        texi2dvi $(PROJECT).texi
 html: dirs $(FILES)
 …
         rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE)
         rm -f $(PROJECT) $(PROJECT)-* $(GENERATED_FILES)
+        rm -f *.fixed _*
+        rm -f *.fixed _* network.t
+#
+#  Grab the chapter on writing a network device driver.
+#
+network.t:
+        ln -s ../networking/driver.t  network.t
+#
 …
         $(BMENU) -p "Makefiles Creating a New BSP Make Customization File" \
             -u "Top" \
             -n "Required Support Routines" ${*}.t
+            -n "Miscellaneous Support Files" ${*}.t
 support.texi: support.t Makefile

doc/bsp_howto/analog.t

-                      r06fee20
+                      rbc950e87
 @chapter Analog Driver
+XXX FILL ME IN
+The Analog driver is responsible for providing an
+interface to Digital to Analog Converters (DACs) and
+Analog to Digital Converters (ADCs).  The capabilities provided
+by this class of device driver are:
+@itemize @bullet
+@item Initialize an Analog Board
+@item Open a Particular Analog
+@item Close a Particular Analog
+@item Read from a Particular Analog
+@item Write to a Particular Analog
+@item Reset DACs
+@item Reinitialize DACS
+@end itemize
+Most analog devices are found on I/O cards that support multiple
+DACs or ADCs on a single card.
+There are currently no analog device drivers included in the
+RTEMS source tree.  The information provided in this chapter
+is based on drivers developed by OAR Corporation personnel
+for applications using RTEMS.   It is hoped that this
+driver model information can form the basis for a standard
+analog driver model that can be supported in future RTEMS
+distribution.
+@section Major and Minor Numbers
+The @b{major} number of a device driver is its index in the
+RTEMS Device Address Table.
+A @b{minor} number is associated with each device instance
+managed by a particular device driver.  An RTEMS minor number
+is an @code{unsigned32} entity.  Convention calls
+dividing the bits in the minor number down into categories
+like the following:
+@itemize @bullet
+@item @b{board} - indicates the board a particular device is located on
+@item @b{port} - indicates the particular device on a board.
+@end itemize
+From the above, it should be clear that a single device driver
+can support multiple copies of the same board in a single system.
+The minor number is used to distinguish the devices.
+@section Analog Driver Configuration
+There is not a standard analog driver configuration table but some
+fields are common across different drivers.  The analog driver
+configuration table is typically an array of structures with each
+structure containing the information for a particular board.
+The following is a list of the type of information normally required
+to configure an analog board:
+@table @b
+@item board_offset
+is the base address of a board.
+@item DAC_initial_values
+is an array of the voltages that should be written to each DAC
+during initialization.  This allows the driver to start the board
+in a known state.
+@end table
+@section Initialize an Analog Board
+At system initialization, the analog driver's initialization entry point
+will be invoked.  As part of initialization, the driver will perform
+whatever board initializatin is required and then set all
+outputs to their configured initial state.
+The analog driver may register a device name for each DAC and ADC in
+the system.
+@section Open a Particular Analog
+This is the driver open call.  Usually this call does nothing other than
+validate the minor number.
+With some drivers, it may be necessary to allocate memory when a particular
+device is opened.  If that is the case, then this is often the place
+to do this operation.
+@section Close a Particular Analog
+This is the driver close call.  Usually this call does nothing.
+With some drivers, it may be necessary to allocate memory when a particular
+device is opened.  If that is the case, then this is the place
+where that memory should be deallocated.
+@section Read from a Particular Analog
+This corresponds to the driver read call.  After validating the minor
+number and arguments, this call reads the indicated device.  Most analog
+devices store the last value written to a DAC.  Since DACs are output
+only devices, saving the last written value gives the appearance that
+DACs can be read from also.  If the device is an ADC, then it is sampled.
+@b{NOTE:} Many boards have multiple analog inputs but only one ADC.  On
+these boards, it will be necessary to provide some type of mutual exclusion
+during reads.  On these boards, there is a MUX which must be switched
+before sampling the ADC.  After the MUX is switched, the driver must
+delay some short period of time (usually microseconds) before the
+signal is stable and can be sampled.  To make matters worse, some ADCs
+cannot respond to wide voltage swings in a single sample.  On these
+ADCs, one must do two samples when the voltage swing is too large.
+On a practical basis, this means that the driver usually ends up
+double sampling the ADC on these systems.
+The value returned is a single precision floating point number
+representing the voltage read.  This value is stored in the
+@code{argument_block} passed in to the call.  By returning the
+voltage, the caller is freed from having to know the number of
+bits in the analog and board dependent conversion algorithm.
+@section Write to a Particular Analog
+This corresponds to the driver write call.  After validating the minor
+number and arguments, this call writes the indicated device.  If the
+specified device is an ADC, then an error is usually returned.
+The value written is a single precision floating point number
+representing the voltage to be written to the specified DAC.
+This value is stored in the @code{argument_block} passed in to the
+call.  By passing the voltage to the device driver, the caller is
+freed from having to know the number of bits in the analog
+and board dependent conversion algorithm.
+@section Reset DACs
+This is one of the IOCTL functions supported by the I/O control
+device driver entry point.  When this IOCTL function is invoked,
+all of the DACs are written to 0.0 volts.
+@section Reinitialize DACS
+This is one of the IOCTL functions supported by the I/O control
+device driver entry point.  When this IOCTL function is invoked,
+all of the DACs are written with the initial value configured
+for this device.
+@section Get Last Written Values
+This is one of the IOCTL functions supported by the I/O control
+device driver entry point.  When this IOCTL function is invoked,
+the last value written to the specified output word along with
+a timestamp of when the last write was performed.

doc/bsp_howto/bsp_howto.texi

r06fee20	rbc950e87
90	90	* Makefiles::
91	91	* Linker Script::
92		* ~~Required Support Routin~~es::
	92	* Miscellaneous Support Files::
93	93	* Initialization Code::
94	94	* Console Driver::

doc/bsp_howto/clock.t

-                      r06fee20
+                      rbc950e87
 @section 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 purpose of the clock driver is to provide a steady time
+basis to the kernel, so that the RTEMS primitives that need
+a clock tick work properly.  See the @code{Clock Manager} chapter
+of the @b{RTEMS Application C User's Guide} for more details.
 The clock driver is located in the clock directory of the BSP.
+The clock driver is located in the @code{clock} directory of the BSP.
 @section Primitives
+@section Clock Driver Global Variables
 @subsection Initialization
+@subsection Major and Minor Number
 The major and minor numbers of the clock driver can be made available to
 the others, such as the Shared Memory Driver.
+The major and minor numbers of the clock driver are made available via
+the following variables.
+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
+@itemize @bullet
+@item rtems_device_major_number rtems_clock_major;
+@item rtems_device_minor_number rtems_clock_minor;
+@end itemize
+The clock device driver is responsible for declaring and
+initializing these variables.  These variables are used
+by other RTEMS components -- notably the Shared Memory Driver.
+@b{NOTE:} In a future RTEMS version, these variables may be replaced
+with the clock device driver registering @b{/dev/clock}.
+@subsection Ticks Counter
+Most of the clock device drivers provide a global variable
+that is simply a count of the number of clock driver interrupt service
+routines that have occured.  This information is valuable when debugging
+a system.  This variable is declared as follows:
+@example
+volatile rtems_unsigned32 Clock_driver_ticks;
+@end example
+@section Initialization
+The initialization routine is responsible for
+programming the hardware that will periodically
+generate an interrupt.  A programmable interval timer is commonly
+used as the source of the clock tick.
+The device should be programmed such that an interrupt is generated
+every @i{m} microseconds, where @i{m} is equal to
+@code{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:
+You must use the RTEMS primitive @code{rtems_interrupt_catch} to install
+your clock interrupt service routine:
 @example
 rtems_interrupt_catch (InterruptHandler, CONSOLE_VECTOR, &old_handler);
+rtems_interrupt_catch (Clock_ISR, CLOCK_VECTOR, &old_handler);
 @end example
+@subsection The Clock Interrupt Subroutine
+Since there is currently not a driver entry point invoked at system
+shutdown, many clock device drivers use the @code{atexit} routine
+to schedule their @code{Clock_exit} routine to execute when the
+system is shutdown.
+By convention, many of the clock drivers do not install the clock
+tick if the @code{ticks_per_timeslice} field of the Configuration
+Table is 0.
+@section System shutdown
+Many drivers provide the routine @code{Clock_exit} that is scheduled
+to be run during system shutdown via the @code{atexit} routine.
+The @code{Clock_exit} routine will disable the clock tick source
+if it was enabled.  This can be used to prevent clock ticks after the
+system is shutdown.
+@section Clock Interrupt Subroutine
 It only has to inform the kernel that a ticker has elapsed, so call :
 @example
+rtems_clock_tick();
+@group
+rtems_isr Clock_isr( rtems_vector_number vector )
+@{
+  invoke the rtems_clock_tick() directive to announce the tick
+  if necessary for this hardware
+    reload the programmable timer
+@}
+@end group
 @end example
+@section IO Control
+The clock driver must supply a handler for the IO control device driver
+entry point.  This functionality is used by other components -- notably
+the Shared Memory Driver to install a wrapper for the clock interrupt
+service routine.  The following shows the functionality required:
+@example
+@group
+rtems_device_driver Clock_control(
+  rtems_device_major_number major,
+  rtems_device_minor_number minor,
+  void *pargp
+)
+@{
+  error check the argument pointer parameter
+  if the command is "ISR"
+    invoke the clock interrupt service routine
+  else if the command is "NEW"
+    install the requested handler
+@}
+@end group
+@end example

doc/bsp_howto/console.t

-                      r06fee20
+                      rbc950e87
 @section 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:
+This chapter describes the operation of a console driver using
+the RTEMS POSIX Termios support.  Traditionally RTEMS has referred
+to all serial device drivers as console device drivers.  A
+console driver can be used to do raw data processing in addition
+to the "normal" standard input and output device functions required
+of a console.
+The serial driver may be called as the consequence of a C Library
+call such as @code{printf} or @code{scanf} or directly via the
+@code{read} or @code{write} system calls.
+There are two main functioning modes:
 @itemize @bullet
 @item console: formatted input/output, with special characters (end of
 line, tabulations, etc...) recognition and processing,
+line, tabulations, etc.) recognition and processing,
 @item raw: permits raw data processing.
 …
 @section 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.
+Termios is a standard for terminal management, included in the POSIX 1003.1b
+standard.  It is commonly provided on UNIX implementations.
+Having RTEMS support for Termios is beneficial:
+@itemize @bullet
+@item from the user's side because it provides standard primitive operations
+to access the terminal and change configuration settings.  These operations
+are the same under Unix and Rtems.
+@item from the BSP developer's side because it frees the
+developer from dealing with buffer states and mutual exclusions on them.
+Early RTEMS console device drivers also did their own special
+character processing.
 @end itemize
 …
 @end itemize
+For more information on Termios, type man termios in your Unix box or go
+to http://www.freebsd.org/cgi/man.cgi.
+At this time, RTEMS documentation does not include a thorough discussion
+of the Termios functionality.  For more information on Termios,
+type @code{man termios} on a Unix box or point a web browser
+at
+@ifset use-html
+@href{http://www.freebsd.org/cgi/man.cgi,,,http://www.freebsd.org/cgi/man.cgi}.
+@end ifset
+@ifclear use-html
+@code{http://www.freebsd.org/cgi/man.cgi}.
+@end ifclear
 @section Driver Functioning Modes
 …
 @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
+@item polled mode
+@item interrupt driven mode
+@end itemize
+In polled mode, the processor blocks on sending/receiving characters.
+This mode is not the most efficient way to utilize the UART. But
+polled mode is usually necessary when one wants to print an
+error message in the event of a fatal error such as al fatal error
+in the BSP.  This is also the simplest mode to
+program.  Polled mode is generally preferred if the serial port is
+to be used primarily as a debug console.  In a simple polled driver,
+the software will continuously check the status of the UART when
+it is reading or writing to the UART.  Termios improves on this
+by delaying the caller for 1 clock tick between successive checks
+of the UART on a read operation.
+In interrupt driven mode, the processor does not block on sending/receiving
+characters.  Data is buffered between the interrupt service routine
+and application code.  Two buffers are used to insulate the application
+from the relative slowness of the serial device.  One of the buffers is
+used for incoming characters, while the other is used for outgoing characters.
+An interrupt is raised when a character is received by the UART.
+The interrupt subroutine places the incoming character at the end
+of the input buffer.  When an application asks for input,
+the characters at the front of the buffer are returned.
+When the application prints to the serial device, the outgoing characters
+are placed at the end of the output buffer.  The driver will place
+one or more characters in the UART (the exact number depends on the UART)
+An interrupt will be raised when all the characters have been transmitted.
+The interrupt service routine has to send the characters
+remaining in the output buffer the same way.   When the transmitting side
+of the UART is idle, it is typically necessary to prime the transmitter
+before the first interrupt will occur.
 @section Serial Driver Functioning Overview
+Figure 5 is an attempt of showing how a Termios driven serial driver works :
+The following Figure shows how a Termios driven serial driver works:
+@example
+This figure needs to be inserted in this document.
+@end example
+The following list describes the basic flow.
 @itemize @bullet
 …
 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.
+@item C library (in fact that's Cygnus Newlib) calls RTEMS
+system call interface. This code can be found in the
+@code{c/src/lib/libc} directory.
+@item Glue code calls the serial driver entry routines.
 @end itemize
 …
 @subsection Termios and Polled I/O
+You have to point Termios out which functions are used for simple
+character input/output:
+Function
+Description
+@example
+The following functions are provided by the driver and invoked by
+Termios for simple character input/output.  The specific names of
+these routines are not important as Termios invokes them indirectly
+via function pointers.
+@subsubsection pollWrite
+The @code{pollWrite} routine is responsible for writing @code{len} characters
+from @code{buf} to the serial device specified by @code{minor}.
+@example
+@group
 int pollWrite (int minor, const char *buf, int len)
 for (i=0; i<len; i++) @{
+@{
+  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.
+@end group
+@end example
+@subsubsection pollRead
+The @code{pollRead} routine is responsible for reading a single character
+from the serial device specified by @code{minor}.  If no character is
+available, then the routine should return -1.
+@example
+@group
+int pollRead(int minor)
+@{
+   read status of UART
+   if status indicates a character is available
+     return character
+   return -1
+@}
+@end group
+@end example
 @subsection Termios and Interrupt Driven 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:
+@example
+core of the driver.
+@subsubsection InterruptHandler
+The @code{InterruptHandler} is responsible for processing asynchronous
+interrupts from the UART.  There may be multiple interrupt handlers for
+a single UART.  Some UARTs can generate a unique interrupt vector for
+each interrupt source such as a character has been received or the
+transmitter is ready for another character.
+In the simplest case, the @code{InterruptHandler} will have to check
+the status of the UART and determine what caused the interrupt.
+The following describes the operation of an @code{InterruptHandler}
+which has to do this:
+@example
+@group
 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.
+@{
+  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.
+@}
+@end group
+@end example
+@subsubsection InterruptWrite
+The @code{InterruptWrite} is responsible for telling the UART
+that the @code{len} characters at @code{buf} are to be transmitted.
 @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
+@{
+   tell the UART to transmit len characters from buf
+@}
+@end example
+The driver has to put the @i{n} first buf characters in the UART channel minor
+buffer (@i{n} is the UART channel size, @i{n}=1 on the MC68640). Generally, an
+interrupt is raised after these @i{n} characters being transmitted. So
+UART interrupts may have to be enabled after putting the characters in the
 UART.
-Figure 5: general TERMIOS driven serial driver functioning
 @subsection Initialization
 The driver initialization is called once during RTEMS initialization
+The driver initialization is called once during the 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:
+The @code{console_initialize} function has to:
+@itemize @bullet
+@item initialize Termios support: call @code{rtems_termios_initialize()}.  If
+Termios has already been initialized by another device driver, then
+this call will have no effect.
+@item Initialize the UART: This procedure should
+be described in the UART manual.  This procedure @b{MUST} be
+followed precisely.  This procedure varies but
+usually consists of:
+@itemize @bullet
+@item reinitialize the UART channels
+@item set the channels configuration to the Termios default:
+bauds, no parity, 1 stop bit, and 8 bits per character
+@end itemize
+@item If interrupt driven, register the console interrupt routine to RTEMS:
 @example
 …
 @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:
+@item enable the UART channels.
+@item register the device name: in order to use the console (i.e. being
+able to do printf/scanf on stdin, stdout, and stderr), some device
+must be registered as "/dev/console":
 @example
 …
 @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
+The @code{console_open} function is called whenever a serial
+device is opened.  The device registered as @code{"/dev/console"}
+is opened automatically during RTEMS initialization.
+For instance, if UART channel 2 is registered as "/dev/tty1",
+the @code{console_open} entry point will be called as
+the result of an @code{fopen("/dev/tty1", mode)} in the
 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 interrupt input/output.
+@end itemize
+The @code{console_open} function has to inform Termios of the low-level
+functions for serial line support; the "callbacks".
+The gen68340 BSP defines two sets of callback tables:
+@itemize @bullet
+@item one with functions for polled input/output
+@item another with functions for interrupt driven input/output
+@end itemize
+This code can be found in the file @code{$BSPROOT/console/console.c}.
 @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.
+Termios must be told the addresses of the functions that are to be
+used for simple character input/output, i.e. pointers to the
+@code{pollWrite} and @code{pollRead} functions
+defined earlier in @ref{Console Driver Termios and Polled I/O}.
 @subsubsection Interrupt Driven 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
+Driver functioning is quite different in this mode.  There is no
+device driver read function to be passed to Termios. Indeed a
+@code{console_read} call returns the contents of Termios input buffer.
+This buffer is filled in the driver interrupt subroutine
+(see @ref{Console Driver Termios and Interrupt Driven I/O}).
+The driver is responsible for providing a pointer to the
+@code{InterruptWrite} function.
+@subsection Closing a Serial Device
+The @code{console_close} is invoked when the serial device is to
+be closed.  This entry point corresponds to the device driver
+close entry point.
+This routine is responsible for notifying Termios that the serial
+device was closed.  This is done with a call to @code{rtems_termios_close}.
+@subsection Reading Characters From a Serial Device
+The @code{console_read} is invoked when the serial device is to
+be read from.  This entry point corresponds to the device driver
+read entry point.
+This routine is responsible for returning the content of the
+Termios input buffer.   This is done by invoking the
+@code{rtems_termios_read} routine.
+@subsection Writing Characters to a Serial Device
+The @code{console_write} is invoked when the serial device is to
+be written to.  This entry point corresponds to the device driver
+write entry point.
+This routine is responsible for adding the requested characters to
+the Termios output queue for this device.  This is done by
+calling the routine @code{rtems_termios_write}
+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.
+@subsection Changing Serial Line Parameters
+The @code{console_control} is invoked when the line parameters
+for a particular serial device are to be changed.
+This entry point corresponds to the device driver
+io_control entry point.
 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.
+with Termios calls (such as the @code{ioctl} command, see
+the Termios documentation for
+more details). If the driver is to support dynamic configuration, then
+is must have the @code{console_control} piece of code. Refer to the gen68340
+BSP for an example of how it is done.  Basically @code{ioctl}
+commands call @code{console_control} with the serial line
+configuration in a Termios defined data structure. The driver
+is responsible for reinitializing the UART with the correct settings.

doc/bsp_howto/discrete.t

-                      r06fee20
+                      rbc950e87
 @chapter Discrete Driver
+XXX FILL ME IN
+The Discrete driver is responsible for providing an
+interface to Discrete Input/Outputs.  The capabilities provided
+by this class of device driver are:
+@itemize @bullet
+@item Initialize a Discrete I/O Board
+@item Open a Particular Discrete Bitfield
+@item Close a Particular Discrete Bitfield
+@item Read from a Particular Discrete Bitfield
+@item Write to a Particular Discrete Bitfield
+@item Reset DACs
+@item Reinitialize DACS
+@end itemize
+Most discrete I/O devices are found on I/O cards that support many
+bits of discrete I/O on a single card.  This driver model is centered
+on the notion of reading bitfields from the card.
+There are currently no discrete I/O device drivers included in the
+RTEMS source tree.  The information provided in this chapter
+is based on drivers developed by OAR Corporation personnel
+for applications using RTEMS.   It is hoped that this
+driver model information can form the basis for a standard
+discrete I/O driver model that can be supported in future RTEMS
+distribution.
+@section Major and Minor Numbers
+The @b{major} number of a device driver is its index in the
+RTEMS Device Address Table.
+A @b{minor} number is associated with each device instance
+managed by a particular device driver.  An RTEMS minor number
+is an @code{unsigned32} entity.  Convention calls for
+dividing the bits in the minor number down into categories
+that specify a particular bitfield.  This results in categories
+like the following:
+@itemize @bullet
+@item @b{board} - indicates the board a particular bitfield is located on
+@item @b{word} - indicates the particular word of discrete bits the
+bitfield is located within
+@item @b{start} - indicates the starting bit of the bitfield
+@item @b{width} - indicates the width of the bitfield
+@end itemize
+From the above, it should be clear that a single device driver
+can support multiple copies of the same board in a single system.
+The minor number is used to distinguish the devices.
+By providing a way to easily access a particular bitfield from
+the device driver, the application is insulated with knowing how
+to mask fields in and out of a discrete I/O.
+@section Discrete I/O Driver Configuration
+There is not a standard discrete I/O driver configuration table but some
+fields are common across different drivers.  The discrete I/O driver
+configuration table is typically an array of structures with each
+structure containing the information for a particular board.
+The following is a list of the type of information normally required
+to configure an discrete I/O board:
+@table @b
+@item board_offset
+is the base address of a board.
+@item relay_initial_values
+is an array of the values that should be written to each output
+word on the board during initialization.  This allows the driver
+to start with the board's output  in a known state.
+@end table
+@section Initialize a Discrete I/O Board
+At system initialization, the discrete I/O driver's initialization entry point
+will be invoked.  As part of initialization, the driver will perform
+whatever board initializatin is required and then set all
+outputs to their configured initial state.
+The discrete I/O driver may register a device name for bitfields of
+particular interest to the system.  Normally this will be restricted
+to the names of each word and, if the driver supports it, an "all words".
+@section Open a Particular Discrete Bitfield
+This is the driver open call.  Usually this call does nothing other than
+validate the minor number.
+With some drivers, it may be necessary to allocate memory when a particular
+device is opened.  If that is the case, then this is often the place
+to do this operation.
+@section Close a Particular Discrete Bitfield
+This is the driver close call.  Usually this call does nothing.
+With some drivers, it may be necessary to allocate memory when a particular
+device is opened.  If that is the case, then this is the place
+where that memory should be deallocated.
+@section Read from a Particular Discrete Bitfield
+This corresponds to the driver read call.  After validating the minor
+number and arguments, this call reads the indicated bitfield.  A
+discrete I/O devices may have to store the last value written to
+a discrete output.  If the bitfield is output only, saving the last
+written value gives the appearance that it can be read from also.
+If the bitfield is input, then it is sampled.
+@b{NOTE:} Many discrete inputs have a tendency to bounce.  The application
+may have to take account for bounces.
+The value returned is an @code{unsigned32} number
+representing the bitfield read.  This value is stored in the
+@code{argument_block} passed in to the call.
+@b{NOTE:} Some discrete I/O drivers have a special minor number
+used to access all discrete I/O bits on the board.  If this special
+minor is used, then the area pointed to by @code{argument_block} must
+be the correct size.
+@section Write to a Particular Discrete Bitfield
+This corresponds to the driver write call.  After validating the minor
+number and arguments, this call writes the indicated device.  If the
+specified device is an ADC, then an error is usually returned.
+The value written is an @code{unsigned32} number
+representing the value to be written to the specified
+bitfield.  This value is stored in the
+@code{argument_block} passed in to the call.
+@b{NOTE:} Some discrete I/O drivers have a special minor number
+used to access all discrete I/O bits on the board.  If this special
+minor is used, then the area pointed to by @code{argument_block} must
+be the correct size.
+@section Disable Discrete Outputs
+This is one of the IOCTL functions supported by the I/O control
+device driver entry point.  When this IOCTL function is invoked,
+the discrete outputs are disabled.
+@b{NOTE:} It may not be possible to disable/enable discrete output on all
+discrete I/O boards.
+@section Enable Discrete Outputs
+This is one of the IOCTL functions supported by the I/O control
+device driver entry point.  When this IOCTL function is invoked,
+the discrete outputs are enabled.
+@b{NOTE:} It may not be possible to disable/enable discrete output on all
+discrete I/O boards.
+@section Reinitialize Outputs
+This is one of the IOCTL functions supported by the I/O control
+device driver entry point.  When this IOCTL function is invoked,
+the discrete outputs are rewritten with the configured initial
+output values.
+@section Get Last Written Values
+This is one of the IOCTL functions supported by the I/O control
+device driver entry point.  When this IOCTL function is invoked,
+the last value written to the specified output word along with
+a timestamp of when the last write was performed.

doc/bsp_howto/init.t

-                      r06fee20
+                      rbc950e87
 initialization code.  Like most BSPs, the initialization for this
 BSP is divided into two subdirectories under the BSP source directory.
+The gen68340 BSP source code in the following directory:
+@example
+c/src/lib/libbsp/m68k/gen68340:
+@end example
+The gen68340 BSP source code is in the following directory:
+@example
+c/src/lib/libbsp/m68k/gen68340
+@end example
+The following source code files are in this subdirectory.
 @itemize @bullet
 …
 contains initialization for a 68349 based board as well.
+@section Required Global Variables
+Although not strictly part of initialization, there are a few global
+variables assumed to exist by many support components.  These
+global variables are usually declared in the file @code{startup/bspstart.c}
+that provides most of the BSP specific initialization.  The following is
+a list of these global variables:
+@itemize @bullet
+@item @code{BSP_Configuration} is the BSP's writable copy of the RTEMS
+Configuration Table.
+@item @code{Cpu_table} is the RTEMS CPU Dependent Information Table.
+@item @code{bsp_isr_level} is the interrupt level that is set at
+system startup.  It will be restored when the executive returns
+control to the BSP.
+@end itemize
 @section Board Initialization
 …
 The @code{boot_card()} is the first C code invoked.  Most of the BSPs
 use the sams shared version of @code{boot_card()} which is located in
+use the same shared version of @code{boot_card()} which is located in
 the following file:
 …
 This routine is also responsible for overriding the default settings
 in the CPU Configuration Table and setting port specific entries
+in this table.  This routine will typically install routines
+for one or more of the following initialization hooks:
+in this table.  This may include increasing the maximum number
+of some types of RTEMS system objects to reflect the needs of
+the BSP and the base set of device drivers. This routine will
+typically also install routines for one or more of the following
+initialization hooks:
 @itemize @bullet
 …
 In addition to the implicit invocation of @code{__main}, this
 routine performs some explitit initialization.  This routine
+routine performs some explicit initialization.  This routine
 sets the variable @code{rtems_progname} and initiates
 multitasking via a call to the RTEMS directive
 …
 RTEMS directive @code{rtems_shutdown_executive} is invoked.
+The RTEMS initialization procedure is described in the @b{Initialization
+Manager} chapter of the @b{RTEMS Application C User's Guide}.
+Please refer to that manual for more information.
 @subsection RTEMS Pretasking Callback
 The @code{pretasking_hook} entry in the RTEMS CPU Configuration
 Table may be the address of a user provided routine that is
 invoked once RTEMS initialization is complete but before interrupts
+invoked once RTEMS API initialization is complete but before interrupts
 and tasking are enabled.  No tasks -- not even the IDLE task -- have
 been created when this hook is invoked.  The pretasking hook is optional.
 …
 The @code{bsp_pretasking_hook()} routine is the appropriate place to
 initialize any support components which depend on the RTEMS APIs.
+Most BSPs initialize the RTEMS C Library support in their
+Most BSPs set the debug level for the system and initialize the
+RTEMS C Library support in their
 implementation of @code{bsp_pretasking_hook()}.  This initialization
+includes the application heap as well as the reentrancy support
+for the C Library.
+includes the application heap used by the @code{malloc} family
+of routines as well as the reentrancy support for the C Library.
+The routine @code{bsp_libc_init} routine invoked from the
+@code{bsp_pretasking_hook()} routine is passed the starting
+address, length, and growth amount passed to @code{sbrk}.
+This "sbrk amount" is only used if the heap runs out of
+memory.  In this case, the RTEMS malloc implementation will
+invoked @code{sbrk} to obtain more memory.  See
+@ref{Miscellaneous Support Files sbrk() Implementation} for more details.
 @subsection RTEMS Predriver Callback
+XXX is the address of the user provided
+routine which is invoked with tasking enabled immediately before
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+but no device drivers are initialized.  This field may be NULL to
+indicate that the hook is not utilized.
+The @code{predriver_hook} entry in the RTEMS CPU Configuration
+Table may be the address of a user provided routine that is
+is invoked immediately before the the device drivers and MPCI
+are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
+Most BSPs do not use this callback.
 @subsection Device Driver Initialization
 …
 At this point in the initialization sequence, the initialization
 routines for all of the device drivers specified in the Device
+Driver Table are invoked.
+Driver Table are invoked.  The initialization routines are invoked
+in the order they appear in the Device Driver Table.
+The Driver Address Table is part of the RTEMS Configuration Table. It
+defines device drivers entry points (initialization, open, close, read,
+write, and control). For more information about this table, please
+refer to the @b{Configuring a System} chapter in the
+@b{RTEMS Application C User's Guide}.
+The RTEMS initialization procedure calls the initialization function for
+every driver defined in the RTEMS Configuration Table (this allows
+one to include 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
 @subsection RTEMS Postdriver Callback
+XXX is the address of the user provided
+routine which is invoked with tasking enabled immediately after
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+and the device drivers are initialized.  This field may be NULL
+to indicate that the hook is not utilized.
+@section 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
+The @code{postdriver_hook} entry in the RTEMS CPU Configuration
+Table may be the address of a user provided routine that is
+invoked immediately after the the device drivers and MPCI are initialized.
+Interrupts and tasking are disabled.  The postdriver hook is optional.
+Although optional, most of the RTEMS BSPs provide a postdriver hook
+callback.  This routine is usually called @code{bsp_postdriver_hook}
+and is found in the file:
+@example
+c/src/lib/libbsp/CPU/BSP/startup/bsppost.c
+@end example
+The @code{bsp_postdriver_hook()} routine is the appropriate place to
+perform initialization that must be performed before the first task
+executes but requires that a device driver be initialized.  The
+shared implementation of the postdriver hook opens the default
+standard in, out, and error files and associates them with
+@code{/dev/console}.
+@section The Interrupt Vector Table
+The Interrupt Vector Table is called different things on different
+processor families but the basic functionality is the same.  Each
+entry in the Table corresponds to the handler routine for a particular
+interrupt source.  When an interrupt from that source occurs, the
+specified handler routine is invoked.  Some context information is
+saved by the processor automatically when this happens.  RTEMS saves
+enough context information so that an interrupt service routine
+can be implemented in a high level language.
+On some processors, the Interrupt Vector Table is at a fixed address.  If
+this address is in RAM, then usually the BSP only has to initialize
+it to contain pointers to default handlers.  If the table is in ROM,
+then the application developer will have to take special steps to
+fill in the table.
+If the base address of the Interrupt Vector Table can be dynamically
+changed to an arbitrary address, then the RTEMS port to that processor
+family will usually allocate its own table and install it.  For example,
+on some members of the Motorola MC68xxx family, the Vector Base Register
+(@code{vbr}) contains this base address.
+@subsection Interrupt Vector Table on the gen68340 BSP
+The gen68340 BSP provides a default Interrupt Vector Table in the
+file @code{$BSP_ROOT/start340/start340.s}.  After the @code{entry}
+label is the definition of space reserved for the table of
+interrupts vectors.  This space is assigned the symbolic name
+of @code{__uhoh} in the @code{gen68340} BSP.
+At @code{__uhoh} label is the default interrupt handler routine. This
+routine is only called when an unexpected interrupts is raised.  One can
+add their own routine there (in that case there's a call to a routine -
+$BSP_ROOT/startup/dumpanic.c - that prints which address caused the
+interrupt and the contents of the registers, stack, etc.), but this should
 not return.
 …
 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 .
+@section Integrated processor registers initialization
+There are always some specific integrated processor registers
+initialization to do. Integrated processors' user manuals often detail
+them.
+@section Data section recopy
+handled by an address decoder, so that the microprocessor knows which
+memory chip(s) to access.   The following figure illustrates this:
+@example
+@group
+                     +-------------------+
+         ------------|                   |
+         ------------|                   |------------
+         ------------|      Address      |------------
+         ------------|      Decoder      |------------
+         ------------|                   |------------
+         ------------|                   |
+                     +-------------------+
+           CPU Bus                           Chip Select
+@end group
+@end example
+The Chip Select registers must be programmed such that they match
+the @code{linkcmds} settings. In the gen68340 BSP, ROM and RAM
+addresses can be found in both the @code{linkcmds} and initialization
+code, but this is not a great way to do this.  It is better to
+define addresses in the linker script.
+@section Integrated Processor Registers Initialization
+The CPUs used in many embedded systems are highly complex devices
+with multiple peripherals on the CPU itself.  For these devices,
+there are always some specific integrated processor registers
+that must be initialized.  Refer to the processors' manuals for
+details on these registers and be VERY careful programming them.
+@section 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).
+@code{$BSP340_ROOT/start340/init68340.c}. First the Interrupt
+Vector Table is copied into RAM, then the data section recopy is initiated
+(_CopyDataClearBSSAndStart in @code{$BSP340_ROOT/start340/startfor340only.s}).
 This code performs the following actions:
 …
 @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.
+(see @ref{Linker Script Initialized Data} for more details about this copy),
+@item clear @code{.bss} section (all the non-initialized
+data will take value 0).
+@end itemize
 @section RTEMS-Specific Initialization
 …
 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>.
+@section 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.
+@table @b
+@item bspstart.c
+It starts the application.  It includes application, board, and monitor
+specific initialization and configuration.
+@item bspstart.c
+@table @b
+@item 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.)
+@end table
+@item bspclean.c
+@table @b
+@item bsp_cleanup
+Return control to the monitor.
+@end table
+@end table
+@section 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
+The RTEMS configuration table is application dependent, which means that
+one has to provide one per application. It is usually defined
+by defining macros and including the header file @code{<confdefs.h>}.
+In simple applications such as the tests provided with RTEMS, it is
+commonly found in the main module of the application.  For more complex
+applications, it may be in a file by itself.
+The header file @code{<confdefs.h>} defines a constant table named
+@code{Configuration}.  It is common practice for the BSP to copy
+this table into a modifiable copy named @code{BSP_Configuration}.
+This copy of the table is modified to define the base address of the
+RTEMS Executive Workspace as well as to reflect any BSP and
+device driver requirements not automatically handled by the application.
+For more information on the RTEMS Configuration Table, refer to the
+@b{RTEMS Application C User's Guide}.

doc/bsp_howto/network.t

-                      r06fee20
+                      rbc950e87
-@c
-@c  COPYRIGHT (c) 1988-1998.
-@c  On-Line Applications Research Corporation (OAR).
-@c  All rights reserved.
-@c
-@c  $Id$
-@c
-@chapter Networking Driver
-XXX FILL ME IN

doc/bsp_howto/nvmem.t

-                      r06fee20
+                      rbc950e87
 @chapter Non-Volatile Memory Driver
+XXX FILL ME IN
+The Non-Volatile driver is responsible for providing an
+interface to various types of non-volatile memory.  These
+types of memory include, but are not limited to, Flash, EEPROM,
+and battery backed RAM.  The capabilities provided
+by this class of device driver are:
+@itemize @bullet
+@item Initialize the Non-Volatile Memory Driver
+@item Optional Disable Read and Write Handlers
+@item Open a Particular Memory Partition
+@item Close a Particular Memory Partition
+@item Read from a Particular Memory Partition
+@item Write to a Particular Memory Partition
+@item Erase the Non-Volatile Memory Area
+@end itemize
+There is currently only one non-volatile device driver included in the
+RTEMS source tree and it does not adhere to this device driver model.
+The information provided in this chapter is based on drivers developed
+by OAR Corporation personnel for applications using RTEMS.   It is
+hoped that this driver model information can form the basis for a standard
+non-volatile memory driver model that can be supported in future RTEMS
+distribution.
+@section Major and Minor Numbers
+The @b{major} number of a device driver is its index in the
+RTEMS Device Address Table.
+A @b{minor} number is associated with each device instance
+managed by a particular device driver.  An RTEMS minor number
+is an @code{unsigned32} entity.  Convention calls
+dividing the bits in the minor number down into categories
+that specify an area of non-volatile memory and a partition
+with that area.  This results in categories
+like the following:
+@itemize @bullet
+@item @b{area} - indicates a block of non-volatile memory
+@item @b{partition} - indicates a particular address range with an area
+@end itemize
+From the above, it should be clear that a single device driver
+can support multiple types of non-volatile memory in a single system.
+The minor number is used to distinguish the types of memory and
+blocks of memory used for different purposes.
+@section Non-Volatile Memory Driver Configuration
+There is not a standard non-volatile driver configuration table but some
+fields are common across different drivers.  The non-volatile memory driver
+configuration table is typically an array of structures with each
+structure containing the information for a particular area of
+non-volatile memory.
+The following is a list of the type of information normally required
+to configure each area of non-volatile memory
+@table @b
+@item memory_type
+is the type of memory device in this area.  Choices are battery backed RAM,
+EEPROM, Flash, or an optional user-supplied type.  If the user-supplied type
+is configured, then the user is responsible for providing a set of
+routines to program the memory.
+@item memory
+is the base address of this memory area.
+@item attributes
+is a pointer to a memory type specific attribute block.  Some of
+the fields commonly contained in this memory type specific attribute
+structure area:
+@table @b
+@item use_protection_algorithm
+is set to TRUE to indicate that the protection (i.e. locking) algorithm
+should be used for this area of non-volatile memory.  A particular
+type of non-volatile memory may not have a protection algorithm.
+@item access
+is an enumerated type to indicate the organization of the memory
+devices in this memory area.  The following is a list of the
+access types supported by the current driver implementation:
+@itemize @bullet
+@item simple unsigned8
+@item simple unsigned16
+@item simple unsigned32
+@item simple unsigned64
+@item single unsigned8 at offset 0 in an unsigned16
+@item single unsigned8 at offset 1 in an unsigned16
+@item single unsigned8 at offset 0 in an unsigned32
+@item single unsigned8 at offset 1 in an unsigned32
+@item single unsigned8 at offset 2 in an unsigned32
+@item single unsigned8 at offset 3 in an unsigned32
+@end itemize
+@item depth
+is the depth of the progamming FIFO on this particular chip.  Some
+chips, particularly EEPROMs, have the same programming algorithm but
+vary in the depth of the amount of data that can be programmed in a single
+block.
+@end table
+@item number_of_partitions
+is the number of logical partitions within this area.
+@item Partitions
+is the address of table that contains an entry to describe each
+partition in this area.  Fields within each element of this
+table are defined as follows:
+@table @b
+@item offset
+is the offset of this partition from the base address of this area.
+@item length
+is the length of this partition.
+@end table
+@end table
+By dividing an area of memory into multiple partitions, it is possible
+to easily divide the non-volatile memory for different purposes.
+@section Initialize the Non-Volatile Memory Driver
+At system initialization, the non-volatile memory driver's
+initialization entry point will be invoked.  As part of
+initialization, the driver will perform
+whatever initializatin is required on each non-volatile memory area.
+The discrete I/O driver may register devices name for memory
+partitions of particular interest to the system.  Normally this
+will be restricted to the device "/dev/nv_memory" to indicate
+the entire device driver.
+@section Disable Read and Write Handlers
+Depending on the target's non-volatile memory configuration, it may be
+possible to write to a status register and make the memory area completely
+inaccessible.  This is target dependent and beyond the standard capabilities
+of any memory type.  The user has the optional capability to provide
+handlers to disable and enable access to a partiticular memory area.
+@section Open a Particular Memory Partition
+This is the driver open call.  Usually this call does nothing other than
+validate the minor number.
+With some drivers, it may be necessary to allocate memory when a particular
+device is opened.  If that is the case, then this is often the place
+to do this operation.
+@section Close a Particular Memory Partition
+This is the driver close call.  Usually this call does nothing.
+With some drivers, it may be necessary to allocate memory when a particular
+device is opened.  If that is the case, then this is the place
+where that memory should be deallocated.
+@section Read from a Particular Memory Partition
+This corresponds to the driver read call.  After validating the minor
+number and arguments, this call enables reads from the specified
+memory area by invoking the user supplied "enable reads handler"
+and then reads the indicated memory area.  When
+invoked the @code{argument_block} is actually a pointer to the following
+structure type:
+@example
+@group
+typedef struct @{
+  rtems_unsigned32   offset;
+  void              *buffer;
+  rtems_unsigned32   length;
+  rtems_unsigned32   status;
+@}   Non_volatile_memory_Driver_arguments;
+@end group
+@end example
+The driver reads @code{length} bytes starting at @code{offset} into
+the partition and places them at @code{buffer}.  The result is returned
+in @code{status}.
+After the read operation is complete, the user supplied "disable reads handler"
+is invoked to protect the memory area again.
+@section Write to a Particular Memory Partition
+This corresponds to the driver write call.   After validating the minor
+number and arguments, this call enables writes to the specified
+memory area by invoking the "enable writes handler", then unprotecting
+the memory area, and finally actually writing to the indicated memory
+area.  When invoked the @code{argument_block} is actually a pointer to
+the following structure type:
+@example
+@group
+typedef struct @{
+  rtems_unsigned32   offset;
+  void              *buffer;
+  rtems_unsigned32   length;
+  rtems_unsigned32   status;
+@}   Non_volatile_memory_Driver_arguments;
+@end group
+@end example
+The driver writes @code{length} bytes from @code{buffer} and
+writes them to the non-volatile memory starting at @code{offset} into
+the partition.  The result is returned in @code{status}.
+After the write operation is complete, the "disable writes handler"
+is invoked to protect the memory area again.
+@section Erase the Non-Volatile Memory Area
+This is one of the IOCTL functions supported by the I/O control
+device driver entry point.  When this IOCTL function is invoked,
+the specified area of non-volatile memory is erased.

doc/bsp_howto/rtc.t

-                      r06fee20
+                      rbc950e87
 @chapter Real-Time Clock Driver
+XXX FILL ME IN
+@section Introduction
+The Real-Time Clock (@b{RTC}) driver is responsible for providing an
+interface to an @b{RTC} device.  [NOTE: In this chapter, the abbreviation
+@b{TOD} is used for @b{Time of Day}.]  The capabilities provided by this
+driver are:
+@itemize @bullet
+@item Set the RTC TOD to RTEMS TOD
+@item Set the RTEMS TOD to the RTC TOD
+@item Get the RTC TOD
+@item Set the RTC TOD to the Specified TOD
+@item Get the Difference Between the RTEMS and RTC TOD
+@end itemize
+The reference implementation for a real-time clock driver can
+be found in @code{c/src/lib/libbsp/shared/tod.c}.  This driver
+is based on the libchip concept and can be easily configured
+to work with any of the RTC chips supported by the RTC
+chip drivers in the directory @code{c/src/lib/lib/libchip/rtc}.
+There is a README file in this directory for each supported
+RTC chip.  Each of these README explains how to configure the
+shared libchip implementation of the RTC driver for that particular
+RTC chip.
+The DY-4 DMV177 BSP uses the shared libchip implementation of the RTC
+driver.  Its @code{RTC_Table} configuration table can be found in
+@code{c/src/lib/libbsp/powerpc/dmv177/tod/config.c}.
+@section Initialization
+The @code{rtc_initialize} routine is responsible for initializing the
+RTC chip so it can be used.  The shared libchip implementation of this
+driver supports multiple RTCs and bases its initialization order on
+the order the chips are defined in the @code{RTC_Table}.  Each chip
+defined in the table may or may not be present on this particular board.
+It is the responsibility of the @code{deviceProbe} to indicate the
+presence of a particular RTC chip.  The first RTC found to be present
+is considered the preferred RTC.
+In the shared libchip based implementation
+of the driver, the following actions are performed:
+@example
+@group
+rtems_device_driver rtc_initialize(
+  rtems_device_major_number  major,
+  rtems_device_minor_number  minor_arg,
+  void                      *arg
+)
+@{
+   for each RTC configured in RTC_Table
+     if the deviceProbe for this RTC indicates it is present
+       set RTC_Minor to this device
+       set RTC_Present to TRUE
+       break out of this loop
+   if RTC_Present is not TRUE
+     return RTEMS_INVALID_NUMBER to indicate that no RTC is present
+   register this minor number as the "/dev/rtc"
+   perform the deviceInitialize routine for the preferred RTC chip
+   for RTCs past this one in the RTC_Table
+     if the deviceProbe for this RTC indicates it is present
+       perform the deviceInitialize routine for this RTC chip
+       register the configured name for this RTC
+@}
+@end group
+@end example
+The @code{deviceProbe} routine returns TRUE if the device
+configured by this entry in the @code{RTC_Table} is present.
+This configuration scheme allows one to support multiple versions
+of the same board with a single BSP.  For example, if the first
+generation of a board had Vendor A's RTC chip and the second
+generation had Vendor B's RTC chip, RTC_Table could contain
+information for both.  The @code{deviceProbe} configured
+for Vendor A's RTC chip would need to return TRUE if the
+board was a first generation one.  The @code{deviceProbe}
+routines are very board dependent.
+@section setRealTimeToRTEMS
+The @code{setRealTimeToRTEMS} routine sets the current RTEMS TOD to that
+of the preferred RTC.
+@example
+@group
+void setRealTimeToRTEMS(void)
+@{
+  if no RTCs are present
+    return
+  invoke the deviceGetTime routine for the preferred RTC
+  set the RTEMS TOD using rtems_clock_set
+@}
+@end group
+@end example
+@section setRealTimeFromRTEMS
+The @code{setRealTimeFromRTEMS} routine sets the preferred RTC TOD to the
+current RTEMS TOD.
+@example
+@group
+void setRealTimeFromRTEMS(void)
+@{
+  if no RTCs are present
+    return
+  obtain the RTEMS TOD using rtems_clock_get
+  invoke the deviceSetTime routine for the preferred RTC
+@}
+@end group
+@end example
+@section getRealTime
+The @code{getRealTime} returns the preferred RTC TOD to the
+caller.
+@example
+@group
+void getRealTime( rtems_time_of_day *tod )
+@{
+  if no RTCs are present
+    return
+  invoke the deviceGetTime routine for the preferred RTC
+@}
+@end group
+@end example
+@section setRealTime
+The @code{setRealTime} routine sets the preferred RTC TOD to the
+TOD specified by the caller.
+@example
+@group
+void setRealTime( rtems_time_of_day *tod )
+@{
+  if no RTCs are present
+    return
+  invoke the deviceSetTime routine for the preferred RTC
+@}
+@end group
+@end example
+@section checkRealTime
+The @code{checkRealTime} routine returns the number of seconds
+difference between the RTC TOD and the current RTEMS TOD.
+@example
+@group
+int checkRealTime( void )
+@{
+  if no RTCs are present
+    return -1
+  obtain the RTEMS TOD using rtems_clock_get
+  get the TOD from the preferred RTC using the deviceGetTime routine
+  convert the RTEMS TOD to seconds
+  convert the RTC TOD to seconds
+  return the RTEMS TOD in seconds - RTC TOD in seconds
+@}
+@end group
+@end example

doc/bsp_howto/shmsupp.t

-                      r06fee20
+                      rbc950e87
 @chapter Shared Memory Support Driver
+XXX FILL ME IN
+The Shared Memory Support Driver is responsible for providing glue
+routines and configuration information required by the Shared
+Memory Multiprocessor Communications Interface (MPCI).  The
+Shared Memory Support Driver tailors the portable Shared
+Memory Driver to a particular target platform.
+This driver is only required in shared memory multiprocessing
+systems that use the RTEMS mulitprocessing support.  For more
+information on RTEMS multiprocessing capabilities and the
+MPCI, refer to the @b{Multiprocessing Manager} chapter
+of the @b{RTEMS Application C User's Guide}.
+@section Shared Memory Configuration Table
+The Shared Memory Configuration Table is defined in the following
+structure:
+@example
+@group
+typedef volatile rtems_unsigned32 vol_u32;
+typedef struct @{
+  vol_u32 *address;        /* write here for interrupt    */
+  vol_u32  value;          /* this value causes interrupt */
+  vol_u32  length;         /* for this length (0,1,2,4)   */
+@} Shm_Interrupt_information;
+struct shm_config_info @{
+  vol_u32           *base;       /* base address of SHM         */
+  vol_u32            length;     /* length (in bytes) of SHM    */
+  vol_u32            format;     /* SHM is big or little endian */
+  vol_u32          (*convert)(); /* neutral conversion routine */
+  vol_u32            poll_intr; /* POLLED or INTR driven mode  */
+  void             (*cause_intr)( rtems_unsigned32 );
+  Shm_Interrupt_information   Intr;     /* cause intr information      */
+@};
+typedef struct shm_config_info shm_config_table;
+@end group
+@end example
+where the fields are defined as follows:
+@table @b
+@item base
+is the base address of the shared memory buffer used to pass
+messages between the nodes in the system.
+@item length
+is the length (in bytes) of the shared memory buffer used to pass
+messages between the nodes in the system.
+@item format
+is either SHM_BIG or SHM_LITTLE to indicate that the neutral format
+of the shared memory area is big or little endian.  The format
+of the memory should be chosen to match most of the inter-node traffic.
+@item convert
+is the address of a routine which converts from native format to
+neutral format.   Ideally, the neutral format is the same as the
+native format so this routine is quite simple.
+@item poll_intr
+is either INTR_MODE or POLLED_MODE to indicate how the node will be
+informed of incoming messages.
+@item cause_intr
+@item Intr
+is the information required to cause an interrupt on a node.  This
+structure contains the following fields:
+@table @b
+@item address
+is the address to write at to cause an interrupt on that node.
+For a polled node, this should be NULL.
+@item value
+is the value to write to cause an interrupt.
+@item length
+is the length of the entity to write on the node to cause an interrupt.
+This can be 0 to indicate polled operation, 1 to write a byte, 2 to
+write a sixteen-bit entity, and 4 to write a thirty-two bit entity.
+@end table
+@end table
+@section Primitives
+@subsection Convert Address
+The @code{Shm_Convert_address} is responsible for converting an address
+of an entity in the shared memory area into the address that should be
+used from this node.  Most targets will simply return the address
+passed to this routine.  However, some target boards will have a special
+window onto the shared memory.  For example, some VMEbus boards have
+special address windows to access addresses that are normally reserved
+in the CPU's address space.
+@example
+@group
+void *Shm_Convert_address( void *address )
+@{
+   return the local address version of this bus address
+@}
+@end group
+@end example
+@subsection Get Configuration
+The @code{Shm_Get_configuration} routine is responsible for filling in the
+Shared Memory Configuration Table passed to it.
+@example
+@group
+void Shm_Get_configuration(
+  rtems_unsigned32   localnode,
+  shm_config_table **shmcfg
+)
+@{
+   fill in the Shared Memory Configuration Table
+@}
+@end group
+@end example
+@subsection Locking Primitives
+This is a collection of routines that are invoked by the portable
+part of the Shared Memory Driver to manage locks in the shared
+memory buffer area.  Accesses to the shared memory must be
+atomic.  Two nodes in a multiprocessor system must not be manipulating
+the shared data structures simultaneously.  The locking primitives
+are used to insure this.
+To avoid deadlock, local processor interrupts should be disabled the entire
+time the locked queue is locked.
+The locking primitives operate on the lock
+@code{field} of the @code{Shm_Locked_queue_Control}
+data structure.  This structure is defined as follows:
+@example
+@group
+typedef struct @{
+  vol_u32 lock;  /* lock field for this queue    */
+  vol_u32 front; /* first envelope on queue      */
+  vol_u32 rear;  /* last envelope on queue       */
+  vol_u32 owner; /* receiving (i.e. owning) node */
+@} Shm_Locked_queue_Control;
+@end group
+@end example
+where each field is defined as follows:
+@table @b
+@item lock
+is the lock field.  Every node in the system must agree on how this
+field will be used.  Many processor families provide an atomic
+"test and set" instruction that is used to manage this field.
+@item front
+is the index of the first message on this locked queue.
+@item rear
+is the index of the last message on this locked queue.
+@item owner
+is the node number of the node that currently has this structure locked.
+@end table
+@subsubsection Initializing a Shared Lock
+The @code{Shm_Initialize_lock} routine is responsible for
+initializing the lock field.  This routines usually is implemented
+as follows:
+@example
+@group
+void Shm_Initialize_lock(
+  Shm_Locked_queue_Control *lq_cb
+)
+@{
+  lq_cb->lock = LQ_UNLOCKED;
+@}
+@end group
+@end example
+@subsubsection Acquiring a Shared Lock
+The @code{Shm_Lock} routine is responsible for
+acquiring the lock field.  Interrupts should be
+disabled while that lock is acquired.  If the lock
+is currently unavailble, then the locking routine
+should delay a few microseconds to allow the other
+node to release the lock.  Doing this reduces bus contention
+for the lock.  This routines usually is implemented as follows:
+@example
+@group
+void Shm_Lock(
+  Shm_Locked_queue_Control *lq_cb
+)
+@{
+  disable processor interrupts
+    set Shm_isrstat to previous interrupt disable level
+    while ( TRUE ) @{
+      atomically attempt to acquire the lock
+      if the lock was acquired
+        return
+      delay some small period of time
+    @}
+@}
+@end group
+@end example
+@subsubsection Releasing a Shared Lock
+The @code{Shm_Unlock} routine is responsible for
+releasing the lock field and reenabling processor
+interrupts.  This routines usually is implemented as follows:
+@example
+@group
+void Shm_Unlock(
+  Shm_Locked_queue_Control *lq_cb
+)
+@{
+  set the lock to the unlocked value
+  reenable processor interrupts to their level prior
+    to the lock being acquired.  This value was saved
+    in the global variable Shm_isrstat
+@}
+@end group
+@end example
+@section Installing the MPCI ISR
+The @code{Shm_setvec} is invoked by the portable portion
+of the shared memory to install the interrupt service routine
+that is invoked when an incoming message is announced.  Some
+target boards support an interprocessor interrupt or mailbox
+scheme and this is where the ISR for that interrupt would be
+installed.
+On an interrupt driven node, this routine would be implemented
+as follows:
+@example
+@group
+void Shm_setvec( void )
+@{
+  install the interprocessor communications ISR
+@}
+@end group
+@end example
+On a polled node, this routine would be empty.

doc/bsp_howto/support.t

-                      r06fee20
+                      rbc950e87
 @c
+@chapter Required Support Routines
+XXX FILL ME IN
+@chapter Miscellaneous Support Files
+@section GCC Compiler Specifications File
+The file @code{bsp_specs} defines the start files and libraries
+that are always used with this BSP.  The format of this file
+is admittedly cryptic and this document will make no attempt
+to explain it completely.  Below is the @code{bsp_specs}
+file from the PowerPC psim BSP:
+@example
+@group
+%rename cpp old_cpp
+%rename lib old_lib
+%rename endfile old_endfile
+%rename startfile old_startfile
+%rename link old_link
+*cpp:
+%(old_cpp) %@{qrtems: -D__embedded__@} -Asystem(embedded)
+*lib:
+%@{!qrtems: %(old_lib)@} %@{qrtems: --start-group \
+%@{!qrtems_debug: -lrtemsall@} %@{qrtems_debug: -lrtemsall_g@} \
+-lc -lgcc --end-group  ecrtn%O%s \
+%@{!qnolinkcmds: -T linkcmds%s@}@}
+*startfile:
+%@{!qrtems: %(old_startfile)@} %@{qrtems:  ecrti%O%s \
+%@{!qrtems_debug: startsim.o%s@} \
+%@{qrtems_debug: startsim_g.o%s@}@}
+*link:
+%@{!qrtems: %(old_link)@} %@{qrtems: -Qy -dp -Bstatic \
+-T linkcmds%s -e _start -u __vectors@}
+@end group
+@end example
+The first section of this file renames the built-in definition of
+some specification variables so they can be augmented without
+embedded their original definition.  The subsequent sections
+specify what behavior is expected when the @code{-qrtems} or
+@code{-qrtems_debug} option is specified.
+The @code{*cpp} definition specifies that when @code{-qrtems}
+is specified, predefine the preprocessor symbol @code{__embedded__}.
+The @code{*lib} section insures that the RTEMS library, BSP specific
+linker script, gcc support library, and the EABI specific @code{ecrtn}
+file are used.
+The @code{*startfile} section specifies that the BSP specific file
+@code{startsim.o} will be used instead of @code{crt0.o}.  In addition,
+the EABI specific file @code{ecrti.o} will be linked in with the
+executable.
+The @code{*link} section specifies the arguments that will be passed to
+the linker.
+The format of this file is specific to the GNU Compiler Suite.  The
+argument used to override and extend the compiler built-in specifications
+is relatively new to the toolset.  The @code{-specs} option is present
+in all @code{egcs} distributions and @code{gcc} distributions starting
+with version 2.8.0.
+@section README Files
+Most BSPs provide one or more @code{README} files.  Generally, there
+is a @code{README} file at the top of the BSP source.  This file
+describes the board and its hardware configuration, provides vendor
+information, local configuration information, information on downloading
+code to the board, debugging, etc..  The intent of this
+file is to help someone begin to use the BSP faster.
+A @code{README} file in a BSP subdirectory typically explains something
+about the contents of that subdirectory in greater detail.  For example,
+it may list the documentation available for a particular peripheral
+controller and how to obtain that documentation.  It may also explain some
+particularly cryptic part of the software in that directory or provide
+rationale on the implementation.
+@section times
+This file contains the results of the RTEMS Timing Test Suite.  It is
+in a standard format so that results from one BSP can be easily compared
+with those of another target board.
+If a BSP supports multiple variants, then there may be multiple @code{times}
+files.  Usually these are named @code{times.VARIANTn}.
+@section Tools Subdirectory
+Some BSPs provide additional tools that aid in using the target board.
+These tools run on the development host and are built as part of building
+the BSP.  Most common is a script to automate running the RTEMS Test Suites
+on the BSP.  Examples of this include:
+@itemize @bullet
+@item @code{powerpc/psim} includes scripts to ease use of the simulator
+@item @code{m68k/mvme162} includes a utility to download across the
+VMEbus into target memory if the host is a VMEbus board in the same
+chasis.
+@item @code{unix/posix} includes scripts to run the tests automatically
+on this BSP.
+@end itemize
+@section bsp.h Include File
+The file @code{include/bsp.h} contains prototypes and definitions
+specific to this board.  Every BSP is required to provide a @code{bsp.h}.
+The best approach to writing a @code{bsp.h} is copying an existing one
+as a starting point.
+Many @code{bsp.h} files provide prototypes of variables defined
+in the linker script (@code{linkcmds}).
+There are a number of fields in this file that are used only by the
+RTEMS Test Suites.  The following is a list of these:
+@itemize @bullet
+@item @code{MAX_LONG_TEST_DURATION} - the longest length of time a
+"long running" test should run.
+@item @code{MAX_SHORT_TEST_DURATION} - the longest length of time a
+"short running" test should run.
+@item @code{MUST_WAIT_FOR_INTERRUPT} - modifies behavior of @code{tm27}.
+@item @code{Install_tm27_vector} - installs the interrupt service
+routine for the Interrupt Benchmark Test (@code{tm27}).
+@item @code{Cause_tm27_intr} - generates the interrupt source
+used in the Interrupt Benchmark Test (@code{tm27}).
+@item @code{Clear_tm27_intr} - clears the interrupt source
+used in the Interrupt Benchmark Test (@code{tm27}).
+@item @code{Lower_tm27_intr} - lowers the interrupt mask so the
+interrupt source used in the Interrupt Benchmark Test (@code{tm27})
+can generate a nested interrupt.
+@end itemize
+@section Calling Overhead File
+The file @code{include/coverhd.h} contains the overhead associated
+with invoking each directive.  This overhead consists of the execution
+time required to package the parameters as well as to execute the "jump to
+subroutine" and "return from subroutine" sequence.  The intent of this
+file is to help separate the calling overhead from the actual execution
+time of a directive.  This file is only used by the tests in the
+RTEMS Timing Test Suite.
+The numbers in this file are obtained by running the "Timer Overhead"
+@code{tmoverhd} test.  The numbers in this file may be 0 and no
+overhead is subtracted from the directive execution times reported by
+the Timing Suite.
+@section sbrk() Implementation
+If the BSP wants to dynamically extend the heap used by the
+C Library memory allocation routines (i.e. @code{malloc} family),
+then this routine must be functional.  The following is the
+prototype for this routine:
+@example
+void * sbrk(size_t increment)
+@end example
+The @code{increment} amount is based upon the @code{sbrk_amount}
+parameter passed to the @code{RTEMS_Malloc_Initialize} during system
+initialization.
+See @ref{Initialization Code RTEMS Pretasking Callback} for more
+information.
+There is a default implementation which returns an error to indicate
+that the heap can not be extended.  This implementation can be
+found in @code{c/src/lib/libbsp/shared/sbrk.c}.  Many of the BSPs
+use this shared implementation.  In order to use this implementation,
+the file @code{Makefile.in} in the BSP's @code{startup} directory
+must be modified so that the @code{$VPATH} variable searches
+both the @code{startup} directory and the shared directory.  The following
+illustates the @code{VPATH} setting in the PowerPC psim BSP's
+@code{startup/Makefile.in}:
+@example
+VPATH = @@srcdir@@:@@srcdir@@/../../../shared
+@end example
+This instructs make to look in all of the directories in the @code{VPATH}
+for the source files.  The directories will be examined in the order
+they are specified.
+@section bsp_cleanup() - Cleanup the Hardware
+The @code{bsp_cleanup()} is the last C code invoked.  Most of the BSPs
+use the same shared version of @code{bsp_cleanup()} that does nothing.
+This implementation is located in the following file:
+@example
+c/src/lib/libbsp/shared/bspclean.c
+@end example
+The @code{bsp_cleanup()} routine can be used to return to a ROM monitor,
+insure that interrupt sources are disabled, etc..  This routine is the
+last place to insure a clean shutdown of the hardware.
+@section set_vector() - Install an Interrupt Vector
+The @code{set_vector} routine is responsible for installing an interrupt
+vector.  It invokes the support routines necessary to install an
+interrupt handler as either a "raw" or an RTEMS interrupt handler.  Raw
+handlers bypass the RTEMS interrupt structure and are responsible for
+saving and restoring all their own registers.  Raw handlers are useful
+for handling traps, debug vectors, etc..
+The @code{set_vector} routine is a central place to perform
+interrupt controller manipulation and encapsulate that information.
+It is usually implemented as follows:
+@example
+@group
+rtems_isr_entry set_vector(                     /* returns old vector */
+  rtems_isr_entry     handler,                  /* isr routine        */
+  rtems_vector_number vector,                   /* vector number      */
+  int                 type                      /* RTEMS or RAW intr  */
+)
+@{
+  if the type is RAW
+    install the raw vector
+  else
+    use rtems_interrupt_catch to install the vector
+  perform any interrupt controller necessary to unmask
+    the interrupt source
+  return the previous handler
+@}
+@end group
+@end example
+@b{NOTE:}  @code{set_vector} is provided by the majority of BSPs but
+not all.  In particular, the i386 BSPs use a different scheme.

doc/bsp_howto/timer.t

-                      r06fee20
+                      rbc950e87
 @chapter Timer Driver
+You can program the timer driver for your own needs, but here are two uses
+of it:
+The timer driver is primarily used by the RTEMS Timing Tests.
+This driver provides as accurate a benchmark timer as possible.
+It typically reports its time in microseconds, CPU cycles, or
+bus cycles.  This information can be very useful for determining
+precisely what pieces of code require optimization and to measure the
+impact of specific minor changes.
+@section UART'S FIFO Full Mode
+The gen68340 BSP also uses the TImer Driver to support a high performance
+mode of the on-CPU UART.
+@section Benchmark Timer
+The RTEMS Timing Test Suite requires a benchmark timer.  The
+RTEMS Timing Test Suite is very helpful for determining
+the performance of target hardware and comparing its performance
+to that of other RTEMS targets.
+This section describes the routines which are assumed to exist by
+the RTEMS Timing Test Suite.  The names used are @b{EXACTLY} what
+is used in the RTEMS Timing Test Suite so follow the naming convention.
+@subsection Timer_initialize
+Initialize the timer source.
+@example
+void Timer_initialize(void)
+@{
+  initialize the benchmark timer
+@}
+@end example
+@subsection Read_timer
+The @code{Read_timer} routine
+returns the number of benchmark time units (typically microseconds)
+that have elapsed since the last call to @code{Timer_initialize}.
+@example
+int Read_timer(void)
+@{
+  stop time = read the hardware timer
+  if the subtract overhead feature is enabled
+    subtract overhead from stop time
+  return the stop time
+@}
+@end example
+Many implementations of this routine subtract the overhead required
+to initialize and read the benchmark timer.  This makes the times reported
+more accurate.
+Some implementations report 0 if the harware timer value change is
+sufficiently small.  This is intended to indicate that the execution time
+is below the resolution of the timer.
+@subsection An Empty Function
+This routine is invoked by the RTEMS Timing Test Suite to measure
+the cost of invoking a subroutine.
+@example
+rtems_status_code Empty_function (void)
+@{
+  return RTEMS_SUCCESSFUL;
+@}
+@end example
+@subsection Set_find_average_overhead
+This routine is invoked by the "Check Timer" (@code{tmck}) test in the
+RTEMS Timing Test Suite.  It makes the @code{Read_timer}
+routine NOT subtract the overhead required
+to initialize and read the benchmark timer.  This is used
+by the @code{tmoverhd} test to determine the overhead
+required to initialize and read the timer.
+@example
+void Set_find_average_overhead(rtems_boolean find_flag)
+@{
+    disable the subtract overhead feature
+@}
+@end example
+The @code{Timer_driver_Find_average_overhead} variable is usually
+used to indicate the state of the "subtract overhead feature".
+@section gen68340 UART 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
+characters have been received (@i{n} is the UART'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
+primitive will block on a receipt of less than @i{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
+waiting in the UART's input FIFO. The delay time has to be set carefully
 otherwise high rates will be broken:
 …
 entered, set a long delay,
 @item otherwise set the delay to the delay needed for n characters
+@item otherwise set the delay to the delay needed for @i{n} characters
 receipt.
 @end itemize
-@section 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 ??????????

doc/networking/driver.t

r06fee20	rbc950e87
9	9	@c
10	10
11		@chapter ~~Writing RTEMS Network Device Drivers~~
	11	@chapter Networking Driver
12	12
13	13	@section Introduction

doc/new_chapters/Makefile

-                      r06fee20
+                      rbc950e87
    io.texi key.texi memorymgmt.texi message.texi mutex.texi procenv.texi \
    process.texi sched.texi semaphores.texi signal.texi systemdb.texi \
+   thread.texi
+   thread.texi \
+   stackchk.texi rtmonuse.texi cpuuse.texi error.texi monitor.texi
 FILES= posix_users.texi preface.texi \
 …
         $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \
             posix_users.texi
 clean:
 …
             -n "" ${*}.t
+stackchk.texi: stackchk.t Makefile
+        $(BMENU) -p "" \
+            -u "Top" \
+            -n "" ${*}.t
+rtmonuse.texi: rtmonuse.t Makefile
+        $(BMENU) -p "" \
+            -u "Top" \
+            -n "" ${*}.t
+cpuuse.texi: cpuuse.t Makefile
+        $(BMENU) -p "" \
+            -u "Top" \
+            -n "" ${*}.t
+error.texi: error.t Makefile
+        $(BMENU) -p "" \
+            -u "Top" \
+            -n "" ${*}.t
+monitor.texi: monitor.t Makefile
+        $(BMENU) -p "" \
+            -u "Top" \
+            -n "" ${*}.t

doc/new_chapters/files.t

-                      r06fee20
+                      rbc950e87
 @item @code{umask} - Sets a file creation mask
 @item @code{link} - Creates a link to a file
+@item @code{symlink} - Creates a symbolic link to a file
+@item @code{readlink} - Obtain the name of the link destination
 @item @code{mkdir} - Makes a directory
 @item @code{mkfifo} - Makes a FIFO special file
 …
 @page
+@subsection symlink - Creates a symbolic link to a file
+@subheading CALLING SEQUENCE:
+@ifset is-C
+@example
+#include <unistd.h>
+int symlink(
+  const char *topath,
+  const char *frompath
+);
+@end example
+@end ifset
+@ifset is-Ada
+@end ifset
+@subheading STATUS CODES:
+@table @b
+@item EACCES
+Search permission is denied for a directory in a file's path prefix
+@item EEXIST
+The named file already exists.
+@item ENAMETOOLONG
+Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
+effect.
+@item ENOENT
+A file or directory does not exist.
+@item ENOSPC
+No space left on disk.
+@item ENOTDIR
+A component of the specified pathname was not a directory when a directory
+was expected.
+@item EPERM
+Operation is not permitted.  Process does not have the appropriate priviledges
+or permissions to perform the requested operations.
+@item EROFS
+Read-only file system.
+@end table
+@subheading DESCRIPTION:
+The @code{symlink()} function creates a symbolic link from the frombath to the
+topath.  The symbolic link will be interpreted at run-time.
+If the @code{symlink()} function fails, no directories are modified.
+The caller may (or may not) need permission to access the existing file.
+@subheading NOTES:
+NONE
+@page
+@subsection readlink - Obtain the name of a symbolic link destination
+@subheading CALLING SEQUENCE:
+@ifset is-C
+@example
+#include <unistd.h>
+int readlink(
+  const char *path,
+  char       *buf,
+  size_t      bufsize
+);
+@end example
+@end ifset
+@ifset is-Ada
+@end ifset
+@subheading STATUS CODES:
+@table @b
+@item EACCES
+Search permission is denied for a directory in a file's path prefix
+@item ENAMETOOLONG
+Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
+effect.
+@item ENOENT
+A file or directory does not exist.
+@item ENOTDIR
+A component of the prefix pathname was not a directory when a directory
+was expected.
+@item ELOOP
+Too many symbolic links were encountered in the pathname.
+@item EINVAL
+The pathname does not refer to a symbolic link
+@item EFAULT
+An invalid pointer was passed into the @code{readlink()} routine.
+@end table
+@subheading DESCRIPTION:
+The @code{readlink()} function places the symbolic link destination into
+@code{buf} argument and returns the number of characters copied.
+If the symbolic link destination is longer than bufsize characters the
+name will be truncated.
+@subheading NOTES:
+NONE
+@page
 @subsection mkdir - Makes a directory

doc/new_chapters/gen_section

-                      r06fee20
+                      rbc950e87
        strpbrk strrchr strspn strstr strtok stlen"
     ;;
+  misc_stackchk)
+    CHAPTER_CAPS="Stack Bounds Checker"
+    CHAPTER_LOWER="stack bounds checker"
+    ROUTINES="Stack_check_Initialize Stack_check_Dump_usage"
+    ;;
+  misc_rtmonuse)
+    CHAPTER_CAPS="Rate Monotonic Period Statistics"
+    CHAPTER_LOWER="rate monotonic period statistics"
+    ROUTINES="Period_usage_Initialize Period_usage_Reset \
+        Period_usage_Update Period_usage_Dump"
+    ;;
+  misc_cpuuse)
+    CHAPTER_CAPS="CPU Usage Statistics"
+    CHAPTER_LOWER="CPU usage statistics"
+    ROUTINES="CPU_usage_Dump CPU_usage_Reset"
+    ;;
+  misc_error)
+    CHAPTER_CAPS="Error Reporting Support"
+    CHAPTER_LOWER="error reporting support"
+    ROUTINES="rtems_error rtems_panic"
+    ;;
+  misc_monitor)
+    CHAPTER_CAPS="Monitor Task"
+    CHAPTER_LOWER="monitor task"
+    ROUTINES="rtems_monitor_init rtems_monitor_wakeup"
+    ;;
   *)
     echo "Unknown chapter name"

doc/new_chapters/posix_users.texi

-                      r06fee20
+                      rbc950e87
 @include confspace.texi
 @include adminiface.texi
+@include stackchk.texi
+@include rtmonuse.texi
+@include cpuuse.texi
+@include error.texi
+@include monitor.texi
 @ifinfo
 @node Top, Preface, (dir), (dir)
 …
 * Configuration Space Manager::
 * Administration Interface Manager::
+* Stack Bounds Checker::
+* Rate Monotonic Period Statistics::
+* CPU Usage Statistics::
+* Error Reporting Support::
+* Monitor Task::
 * Command and Variable Index::
 * Concept Index::

doc/new_chapters/signal.t

r06fee20	rbc950e87
109	109	@subheading NOTES:
110	110
	111	NONE
	112
111	113	@page
112	114	@subsection sigdelset - Delete a Signal from a Signal Set

doc/posix1003.1/Makefile

r06fee20	rbc950e87
46	46	$(PROJECT).dvi: $(FILES)
47	47	$(TEXI2DVI) -v $(PROJECT).texi
48		texi2dvi $(PROJECT).texi
	48	texi2dvi -v $(PROJECT).texi
49	49
50	50	ch01.texi: ch01.t

doc/posix1003.1/ch06.t

r06fee20	rbc950e87
23	23	@example
24	24	dup(), Function, Implemented
25		dup2(), Function, Untested Implementation
	25	dup2(), Function, Untested Iimplementation
26	26	@end example
27	27

doc/posix1003.1/ch14.t

-                      r06fee20
+                      rbc950e87
 @example
 timer_create(), Function, Implemented
+timer_create(), Function, Dummy Implementation
 @end example
 …
 @example
 timer_delete(), Function, Implemented
+timer_delete(), Function, Dummy Implementation
 @end example
 …
 @example
 timer_settime(), Function, Implemented
 timer_gettime(), Function, Implemented
 timer_getoverrun(), Function, Implemented
+timer_settime(), Function, Dummy Implementation
+timer_gettime(), Function, Dummy Implementation
+timer_getoverrun(), Function, Dummy Implementation
 @end example

doc/started/Makefile

-                      r06fee20
+                      rbc950e87
 # run texi2dvi twice to generate the xref's properly.
 $(PROJECT).dvi: $(FILES)
         $(TEXI2DVI) $(PROJECT).texi
         texi2dvi $(PROJECT).texi
+        $(TEXI2DVI) -v $(PROJECT).texi
+        texi2dvi -v $(PROJECT).texi
 intro.texi: intro.t versions.texi

doc/supplements/hppa1_1/cputable.t

-                      r06fee20
+                      rbc950e87
 @table @code
 @item pretasking_hook
 is the address of the
+user provided routine which is invoked once RTEMS initialization
+is complete but before interrupts and tasking are enabled.  This
 field may be NULL to indicate that the hook is not utilized.
+is the address of the user provided routine which is invoked
+once RTEMS APIs are initialized.  This routine will be invoked
+before any system tasks are created.  Interrupts are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item predriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately before
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+but no device drivers are initialized.  This field may be NULL to
+indicate that the hook is not utilized.
+routine that is invoked immediately before the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item postdriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately after
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+and the device drivers are initialized.  This field may be NULL
+to indicate that the hook is not utilized.
+routine that is invoked immediately after the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item idle_task

doc/supplements/i386/cputable.t

-                      r06fee20
+                      rbc950e87
 @table @code
 @item pretasking_hook
 is the address of the
+user provided routine which is invoked once RTEMS initialization
+is complete but before interrupts and tasking are enabled.  This
 field may be NULL to indicate that the hook is not utilized.
+is the address of the user provided routine which is invoked
+once RTEMS APIs are initialized.  This routine will be invoked
+before any system tasks are created.  Interrupts are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item predriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately before
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+but no device drivers are initialized.  This field may be NULL to
+indicate that the hook is not utilized.
+routine that is invoked immediately before the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item postdriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately after
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+and the device drivers are initialized.  This field may be NULL
+to indicate that the hook is not utilized.
+routine that is invoked immediately after the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item idle_task

doc/supplements/i960/cputable.t

-                      r06fee20
+                      rbc950e87
 @table @code
 @item pretasking_hook
 is the address of the
+user provided routine which is invoked once RTEMS initialization
+is complete but before interrupts and tasking are enabled.  This
 field may be NULL to indicate that the hook is not utilized.
+is the address of the user provided routine which is invoked
+once RTEMS APIs are initialized.  This routine will be invoked
+before any system tasks are created.  Interrupts are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item predriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately before
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+but no device drivers are initialized.  This field may be NULL to
+indicate that the hook is not utilized.
+routine that is invoked immediately before the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item postdriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately after
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+and the device drivers are initialized.  This field may be NULL
+to indicate that the hook is not utilized.
+routine that is invoked immediately after the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item idle_task

doc/supplements/m68k/cputable.t

-                      r06fee20
+                      rbc950e87
 @table @code
 @item pretasking_hook
 is the address of the
+user provided routine which is invoked once RTEMS initialization
+is complete but before interrupts and tasking are enabled.  This
 field may be NULL to indicate that the hook is not utilized.
+is the address of the user provided routine which is invoked
+once RTEMS APIs are initialized.  This routine will be invoked
+before any system tasks are created.  Interrupts are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item predriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately before
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+but no device drivers are initialized.  This field may be NULL to
+indicate that the hook is not utilized.
+routine that is invoked immediately before the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item postdriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately after
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+and the device drivers are initialized.  This field may be NULL
+to indicate that the hook is not utilized.
+routine that is invoked immediately after the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item idle_task

doc/supplements/powerpc/cputable.t

-                      r06fee20
+                      rbc950e87
 @table @code
 @item pretasking_hook
 is the address of the
+user provided routine which is invoked once RTEMS initialization
+is complete but before interrupts and tasking are enabled.  This
 field may be NULL to indicate that the hook is not utilized.
+is the address of the user provided routine which is invoked
+once RTEMS APIs are initialized.  This routine will be invoked
+before any system tasks are created.  Interrupts are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item predriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately before
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+but no device drivers are initialized.  This field may be NULL to
+indicate that the hook is not utilized.
+routine that is invoked immediately before the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item postdriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately after
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+and the device drivers are initialized.  This field may be NULL
+to indicate that the hook is not utilized.
+routine that is invoked immediately after the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item idle_task

doc/supplements/sparc/cputable.t

-                      r06fee20
+                      rbc950e87
 @table @code
 @item pretasking_hook
 is the address of the
+user provided routine which is invoked once RTEMS initialization
+is complete but before interrupts and tasking are enabled.  This
 field may be NULL to indicate that the hook is not utilized.
+is the address of the user provided routine which is invoked
+once RTEMS APIs are initialized.  This routine will be invoked
+before any system tasks are created.  Interrupts are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item predriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately before
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+but no device drivers are initialized.  This field may be NULL to
+indicate that the hook is not utilized.
+routine that is invoked immediately before the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item postdriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately after
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+and the device drivers are initialized.  This field may be NULL
+to indicate that the hook is not utilized.
+routine that is invoked immediately after the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item idle_task

doc/supplements/template/cputable.t

-                      r06fee20
+                      rbc950e87
 @table @code
 @item pretasking_hook
 is the address of the
+user provided routine which is invoked once RTEMS initialization
+is complete but before interrupts and tasking are enabled.  This
 field may be NULL to indicate that the hook is not utilized.
+is the address of the user provided routine which is invoked
+once RTEMS APIs are initialized.  This routine will be invoked
+before any system tasks are created.  Interrupts are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item predriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately before
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+but no device drivers are initialized.  This field may be NULL to
+indicate that the hook is not utilized.
+routine that is invoked immediately before the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item postdriver_hook
 is the address of the user provided
+routine which is invoked with tasking enabled immediately after
+the MPCI and device drivers are initialized. RTEMS
+initialization is complete, interrupts and tasking are enabled,
+and the device drivers are initialized.  This field may be NULL
+to indicate that the hook is not utilized.
+routine that is invoked immediately after the
+the device drivers and MPCI are initialized. RTEMS
+initialization is complete but interrupts and tasking are disabled.
+This field may be NULL to indicate that the hook is not utilized.
 @item idle_task

Context Navigation

Changeset bc950e87 in rtems

Legend:

doc/bsp_howto/Makefile

doc/bsp_howto/analog.t

doc/bsp_howto/bsp_howto.texi

doc/bsp_howto/clock.t

doc/bsp_howto/console.t

doc/bsp_howto/discrete.t

doc/bsp_howto/init.t

doc/bsp_howto/network.t

doc/bsp_howto/nvmem.t

doc/bsp_howto/rtc.t

doc/bsp_howto/shmsupp.t

doc/bsp_howto/support.t

doc/bsp_howto/timer.t

doc/networking/driver.t

doc/new_chapters/Makefile

doc/new_chapters/files.t

doc/new_chapters/gen_section

doc/new_chapters/posix_users.texi

doc/new_chapters/signal.t

doc/posix1003.1/Makefile

doc/posix1003.1/ch06.t

doc/posix1003.1/ch14.t

doc/started/Makefile

doc/supplements/hppa1_1/cputable.t

doc/supplements/i386/cputable.t

doc/supplements/i960/cputable.t

doc/supplements/m68k/cputable.t

doc/supplements/powerpc/cputable.t

doc/supplements/sparc/cputable.t

doc/supplements/template/cputable.t

Download in other formats: