RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

Applied updates from remote work while doing class.

Browse Source
This commit is contained in:
Joel Sherrill
1998-11-19 16:02:06 +00:00
parent 06fee20ac1
commit bc950e878a
30 changed files with 2144 additions and 451 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
doc/bsp_howto/Makefile
View File

@@ -44,7 +44,7 @@ $(PROJECT).ps: $(PROJECT).dvi
# run texi2dvi twice to generate the xref's properly.
$(PROJECT).dvi: $(FILES)
$(TEXI2DVI) $(PROJECT).texi
$(TEXI2DVI) $(PROJECT).texi
texi2dvi $(PROJECT).texi
html: dirs $(FILES)
-mkdir -p $(WWW_INSTALL)/$(PROJECT)
@@ -55,7 +55,14 @@ clean:
rm -f *.o $(PROG) *.txt core
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
#
# Process Automatically Generated Files
@@ -79,7 +86,7 @@ makefiles.texi: makefiles.t Makefile
linkcmds.texi: linkcmds.t Makefile
$(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
$(BMENU) -p "Linker Script Initialized Data" \

153
doc/bsp_howto/analog.t
View File

@@ -8,5 +8,156 @@
@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.

2
doc/bsp_howto/bsp_howto.texi
View File

@@ -89,7 +89,7 @@ This is the online version of the Getting Started with RTEMS for C/C++ Users.
* Target Dependent Files::
* Makefiles::
* Linker Script::
* Required Support Routines::
* Miscellaneous Support Files::
* Initialization Code::
* Console Driver::
* Clock Driver::

115
doc/bsp_howto/clock.t
View File

@@ -10,37 +10,120 @@
@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

334
doc/bsp_howto/console.t
View File

@@ -10,16 +10,22 @@
@section Introduction
This chapter describes how to do a console driver using RTEMS Termios
support.
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 is called as soon as printf/scanf or read/write kind of
input/output are needed. There are two main functioning modes:
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.
@@ -30,16 +36,20 @@ of data, but Termios permits having only one driver.
@section Termios
Termios is a standard for terminal management, included in several Unix
versions. Termios is good because:
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: primitives to access the terminal and change
configuration settings are the same under Unix and Rtems.
@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: it frees you from dealing with buffer
states and mutual exclusions on them.
@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
@@ -54,8 +64,16 @@ Timeout.
@end itemize
For more information on Termios, type man termios in your Unix box or go
to http://www.freebsd.org/cgi/man.cgi.
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
@@ -64,130 +82,203 @@ Asynchronous Receiver-Transmitter, i.e. the serial chip):
@itemize @bullet
@item polling mode: the processor blocks on sending/receiving characters.
This mode is not powerful, but is necessary when one wants to print an
error message when the board hung. This is also the most simple mode to
program,
@item interrupt mode: the processor doesn't block on sending/receiving
characters. Two buffers (one for the in-going characters, the others for
the characters to be sent) are used. An interrupt is raised as soon as a
character is in the UART. Then the int errupt subroutine insert the
character at the input buffer queue. When a character is asked for input,
this at the head of the buffer is returned. When characters have to be
sent, one have to put the first characters (the number depends on the
UART) in th e UART. Then an interrupt is raised when all the characters
have been emitted. The interrupt subroutine has to send the characters
remaining in the output buffer the same way.
@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
@item the application programmer uses standard C library call (printf,
scanf, read, write, etc.),
@item C library (in fact that's Cygnus Newlib) calls RTEMS procedure: glue
is made in newlib*.c files which can be found under
$RTEMS_ROOT/c/src/lib/libc directory,
@item 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 your serial driver entry routines.
@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:
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
Function
Description
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 group
@end example
wait for a character to be available in the UART channel minor, then return it.
@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:
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)
@{
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
check whether there was an error
@subsubsection InterruptWrite
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.
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)
@{
tell the UART to transmit len characters from buf
@}
@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
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 :
The @code{console_initialize} function has to:
@itemize @bullet
@item initialize Termios support: call rtems_termios_initialize(),
@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 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 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:
@item reinitialize the UART channels,
@itemize @bullet
@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 set the channels configuration to the Termios default:
9600 bauds, no parity, 1 stop bit, and 8 bits per character
@end itemize
@item register your console interrupt routine to RTEMS:
@item If interrupt driven, register the console interrupt routine to RTEMS:
@example
rtems_interrupt_catch (InterruptHandler,CONSOLE_VECTOR,&old_handler);
@end example
@item enable the UART channels,
@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 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
rtems_io_register_name ("dev/console", major, i);
@@ -197,73 +288,92 @@ rtems_io_register_name ("dev/console", major, i);
@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 @code{console_open} function has to inform Termios of the low-level
functions for serial line support; the "callbacks".
The gen68340 BSP defines two kinds of callbacks:
The gen68340 BSP defines two sets of callback tables:
@itemize @bullet
@item functions to use with polled input/output,
@item one with functions for polled input/output
@item functions to use with interrupt 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).
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}).
But you actually have to provide a pointer to the InterruptWrite function.
The driver is responsible for providing a pointer to the
@code{InterruptWrite} function.
@subsection Closing a serial device
@subsection Closing a Serial Device
The driver entry point is: console_close.
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.
You just have to notify Termios that the serial device was closed, with a
call to rtems_termios_close.
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 the serial device
@subsection Reading Characters From a Serial Device
The driver entry point is: console_read.
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.
You just have to return the content of the Termios input buffer.
This routine is responsible for returning the content of the
Termios input buffer. This is done by invoking the
@code{rtems_termios_read} routine.
Call rtems_termios_read.
@subsection Writing Characters to a Serial Device
@subsection Writing characters to the 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.
The driver entry point is: console_write.
You just have to add the characters at the end of the Termios output
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
@subsection Changing serial line parameters
The driver entry point is: console_control.
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.

173
doc/bsp_howto/discrete.t
View File

@@ -8,5 +8,176 @@
@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.

351
doc/bsp_howto/init.t
View File

@@ -21,12 +21,14 @@ as interrupt vector table and chip select initialization.
Most of the examples in this chapter will be based on the gen68340 BSP
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:
The gen68340 BSP source code is in the following directory:
@example
c/src/lib/libbsp/m68k/gen68340:
c/src/lib/libbsp/m68k/gen68340
@end example
The following source code files are in this subdirectory.
@itemize @bullet
@item @code{start340}: assembly language code which contains early
@@ -45,6 +47,26 @@ In the @code{start340} directory are two source files. The file
initialization code for a MC68340 board. The file @code{start340.s}
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
This section describes the steps an application goes through from the
@@ -76,7 +98,7 @@ invoking the shared routine @code{boot_card()}.
@subsection boot_card() - Boot the Card
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:
@example
@@ -128,8 +150,11 @@ c/src/lib/libbsp/CPU/BSP/startup/bspstart.c
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
@item BSP Pretasking Hook
@@ -172,18 +197,22 @@ c/src/lib/libbsp/shared/main.c
@end example
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
@code{rtems_initialize_executive_late}. It is important to note
that the executive does not return to this routine until the
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.
@@ -197,157 +226,47 @@ c/src/lib/libbsp/CPU/BSP/startup/bspstart.c
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.
@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
not return.
@section Chip Select Initialization
When the microprocessor accesses a memory area, address decoding is
handled by an address decoder (!), so that the microprocessor knows which
memory chip to access.
Figure 4 : address decoding
You have to program your Chip Select registers in order that they match
the linkcmds settings. In this BSP ROM and RAM addresses can be found in
both the linkcmds and initialization code, but this is not a great way to
do, better use some shared variables .
@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
The next initialization part can be found in
$BSP340_ROOT/start340/init68340.c. First the Interrupt Vector Table is
copied into RAM, then the data section recopy is initiated
(_CopyDataClearBSSAndStart in $BSP340_ROOT/start340/startfor340only.s).
This code performs the following actions:
@itemize @bullet
@item copies the .data section from ROM to its location reserved in RAM
(see 5.2 for more details about this copy),
@item clear .bss section (all the non-initialized data will take value 0).
@end itemize
Then control is passed to the RTEMS-specific initialization code.
@section RTEMS-Specific Initialization
@section The RTEMS configuration table
The RTEMS configuration table contains the maximum number of objects RTEMS
can handle during the application (e.g. maximum number of tasks,
semaphores, etc.). It's used to allocate the size for the RTEMS inner data
structures.
The RTEMS configuration table is application dependant, which means that
one has to provide one per application. It's usually an header file
included in the main module of the application.
The BSP_Configuration label points on this table.
For more information on the RTEMS configuration table, refer to C user's
guide, chapter 23 <insert a link here>.
@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 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 permits to add
only the drivers needed by the application).
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:
@@ -362,3 +281,143 @@ channels in the UART).
@end itemize
@subsection RTEMS Postdriver Callback
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.
@section Chip Select Initialization
When the microprocessor accesses a memory area, address decoding is
handled by an address decoder, so that the microprocessor knows which
memory chip(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
@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:
@itemize @bullet
@item copies the .data section from ROM to its location reserved in RAM
(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
@section The RTEMS configuration table
The RTEMS configuration table contains the maximum number of objects RTEMS
can handle during the application (e.g. maximum number of tasks,
semaphores, etc.). It's used to allocate the size for the RTEMS inner data
structures.
The RTEMS configuration table is application 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}.

12
doc/bsp_howto/network.t
View File

@@ -1,12 +0,0 @@
@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

225
doc/bsp_howto/nvmem.t
View File

@@ -8,5 +8,228 @@
@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.

177
doc/bsp_howto/rtc.t
View File

@@ -8,5 +8,180 @@
@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

259
doc/bsp_howto/shmsupp.t
View File

@@ -8,5 +8,262 @@
@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.

249
doc/bsp_howto/support.t
View File

@@ -6,7 +6,252 @@
@c $Id$
@c
@chapter Required Support Routines
@chapter Miscellaneous Support Files
XXX FILL ME IN
@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.

135
doc/bsp_howto/timer.t
View File

@@ -8,19 +8,103 @@
@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:
@itemize @bullet
@@ -28,47 +112,10 @@ otherwise high rates will be broken:
@item if no character was received last time the interrupt subroutine was
entered, set a long delay,
@item otherwise set the delay to the delay needed for n characters
@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 ??????????

2
doc/networking/driver.t
View File

@@ -8,7 +8,7 @@
@c $Id$
@c
@chapter Writing RTEMS Network Device Drivers
@chapter Networking Driver
@section Introduction

28
doc/new_chapters/Makefile
View File

@@ -23,7 +23,8 @@ GENERATED_FILES= \
cspecific.texi device.texi dumpcontrol.texi eventlog.texi files.texi \
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 \
$(COMMON_FILES) $(GENERATED_FILES)
@@ -54,7 +55,6 @@ html: dirs $(FILES)
$(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \
posix_users.texi
clean:
rm -f *.o $(PROG) *.txt core *.html
rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE)
@@ -170,3 +170,27 @@ systemdb.texi: systemdb.t Makefile
-u "Top" \
-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

129
doc/new_chapters/files.t
View File

@@ -28,6 +28,8 @@ The directives provided by the files and directories manager are:
@item @code{creat} - Create a new file or rewrite an existing one
@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
@item @code{unlink} - Removes a directory entry
@@ -740,6 +742,133 @@ The caller may (or may not) need permission to access the existing file.
NONE
@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

26
doc/new_chapters/gen_section
View File

@@ -129,6 +129,32 @@ case ${chapter} in
ROUTINES="strcpy strncpy strcat strncat strcmp strncmp strchr strcspn \
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"
exit 1

10
doc/new_chapters/posix_users.texi
View File

@@ -107,6 +107,11 @@ END-INFO-DIR-ENTRY
@include dumpcontrol.texi
@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)
@top posix_users_new
@@ -137,6 +142,11 @@ This is the online version of the RTEMS POSIX API User's Guide
* Process Dump Control Manager::
* 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::
@end menu

2
doc/new_chapters/signal.t
View File

@@ -108,6 +108,8 @@ This function adds the @code{signo} to the specified signal @code{set}.
@subheading NOTES:
NONE
@page
@subsection sigdelset - Delete a Signal from a Signal Set

2
doc/posix1003.1/Makefile
View File

@@ -45,7 +45,7 @@ $(PROJECT).ps: $(PROJECT).dvi
# run texi2dvi twice to generate the xref's properly.
$(PROJECT).dvi: $(FILES)
$(TEXI2DVI) -v $(PROJECT).texi
texi2dvi $(PROJECT).texi
texi2dvi -v $(PROJECT).texi
ch01.texi: ch01.t
$(BMENU) -c -p "Preface" \

2
doc/posix1003.1/ch06.t
View File

@@ -22,7 +22,7 @@ pipe(), Function, Dummy Implementation
@example
dup(), Function, Implemented
dup2(), Function, Untested Implementation
dup2(), Function, Untested Iimplementation
@end example
@section File Descriptor Deassignment

10
doc/posix1003.1/ch14.t
View File

@@ -46,21 +46,21 @@ clock_getres(), Function, Implemented
@subsection Create a Per-Process Timer
@example
timer_create(), Function, Implemented
timer_create(), Function, Dummy Implementation
@end example
@subsection Delete a Per-Process Timer
@example
timer_delete(), Function, Implemented
timer_delete(), Function, Dummy Implementation
@end example
@subsection Per-Process Timers
@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
@subsection High Resolution Sleep

4
doc/started/Makefile
View File

@@ -41,8 +41,8 @@ $(PROJECT).ps: $(PROJECT).dvi
# 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
$(BMENU) -c -p "Top" \

26
doc/supplements/hppa1_1/cputable.t
View File

@@ -47,26 +47,24 @@ typedef struct @{
@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
is the address of the optional user

26
doc/supplements/i386/cputable.t
View File

@@ -46,26 +46,24 @@ typedef struct @{
@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
is the address of the optional user

26
doc/supplements/i960/cputable.t
View File

@@ -54,26 +54,24 @@ by including the file rtems.h.
@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
is the address of the optional user

26
doc/supplements/m68k/cputable.t
View File

@@ -47,26 +47,24 @@ typedef struct @{
@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
is the address of the optional user

26
doc/supplements/powerpc/cputable.t
View File

@@ -54,26 +54,24 @@ typedef struct @{
@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
is the address of the optional user

26
doc/supplements/sparc/cputable.t
View File

@@ -43,26 +43,24 @@ typedef struct @{
@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
is the address of the optional user

26
doc/supplements/template/cputable.t
View File

@@ -47,26 +47,24 @@ typedef struct @{
@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
is the address of the optional user