Changeset bc950e87 in rtems


Ignore:
Timestamp:
Nov 19, 1998, 4:02:06 PM (21 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
d82f3e81
Parents:
06fee20
Message:

Applied updates from remote work while doing class.

Location:
doc
Files:
30 edited

Legend:

Unmodified
Added
Removed
  • doc/bsp_howto/Makefile

    r06fee20 rbc950e87  
    4545$(PROJECT).dvi: $(FILES)
    4646        $(TEXI2DVI) $(PROJECT).texi
    47         $(TEXI2DVI) $(PROJECT).texi
     47        texi2dvi $(PROJECT).texi
    4848
    4949html: dirs $(FILES)
     
    5656        rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE)
    5757        rm -f $(PROJECT) $(PROJECT)-* $(GENERATED_FILES)
    58         rm -f *.fixed _*
     58        rm -f *.fixed _* network.t
     59
     60#
     61#  Grab the chapter on writing a network device driver.
     62#
     63network.t:
     64        ln -s ../networking/driver.t  network.t
     65
    5966
    6067#
     
    8087        $(BMENU) -p "Makefiles Creating a New BSP Make Customization File" \
    8188            -u "Top" \
    82             -n "Required Support Routines" ${*}.t
     89            -n "Miscellaneous Support Files" ${*}.t
    8390
    8491support.texi: support.t Makefile
  • doc/bsp_howto/analog.t

    r06fee20 rbc950e87  
    99@chapter Analog Driver
    1010
    11 XXX FILL ME IN
     11The Analog driver is responsible for providing an
     12interface to Digital to Analog Converters (DACs) and
     13Analog to Digital Converters (ADCs).  The capabilities provided
     14by this class of device driver are:
    1215
     16@itemize @bullet
     17@item Initialize an Analog Board
     18@item Open a Particular Analog
     19@item Close a Particular Analog
     20@item Read from a Particular Analog
     21@item Write to a Particular Analog
     22@item Reset DACs
     23@item Reinitialize DACS
     24@end itemize
     25
     26Most analog devices are found on I/O cards that support multiple
     27DACs or ADCs on a single card.
     28
     29There are currently no analog device drivers included in the
     30RTEMS source tree.  The information provided in this chapter
     31is based on drivers developed by OAR Corporation personnel
     32for applications using RTEMS.   It is hoped that this
     33driver model information can form the basis for a standard
     34analog driver model that can be supported in future RTEMS
     35distribution.
     36
     37@section Major and Minor Numbers
     38
     39The @b{major} number of a device driver is its index in the
     40RTEMS Device Address Table.
     41
     42A @b{minor} number is associated with each device instance
     43managed by a particular device driver.  An RTEMS minor number
     44is an @code{unsigned32} entity.  Convention calls
     45dividing the bits in the minor number down into categories
     46like the following:
     47
     48@itemize @bullet
     49
     50@item @b{board} - indicates the board a particular device is located on
     51@item @b{port} - indicates the particular device on a board.
     52
     53@end itemize
     54
     55From the above, it should be clear that a single device driver
     56can support multiple copies of the same board in a single system.
     57The minor number is used to distinguish the devices.
     58
     59@section Analog Driver Configuration
     60
     61There is not a standard analog driver configuration table but some
     62fields are common across different drivers.  The analog driver
     63configuration table is typically an array of structures with each
     64structure containing the information for a particular board.
     65The following is a list of the type of information normally required
     66to configure an analog board:
     67
     68@table @b
     69@item board_offset
     70is the base address of a board.
     71
     72@item DAC_initial_values
     73is an array of the voltages that should be written to each DAC
     74during initialization.  This allows the driver to start the board
     75in a known state.
     76
     77@end table
     78
     79@section Initialize an Analog Board
     80
     81At system initialization, the analog driver's initialization entry point
     82will be invoked.  As part of initialization, the driver will perform
     83whatever board initializatin is required and then set all
     84outputs to their configured initial state.
     85
     86The analog driver may register a device name for each DAC and ADC in
     87the system.
     88
     89@section Open a Particular Analog
     90
     91This is the driver open call.  Usually this call does nothing other than
     92validate the minor number. 
     93
     94With some drivers, it may be necessary to allocate memory when a particular
     95device is opened.  If that is the case, then this is often the place
     96to do this operation.
     97
     98@section Close a Particular Analog
     99
     100This is the driver close call.  Usually this call does nothing.
     101
     102With some drivers, it may be necessary to allocate memory when a particular
     103device is opened.  If that is the case, then this is the place
     104where that memory should be deallocated.
     105
     106@section Read from a Particular Analog
     107
     108This corresponds to the driver read call.  After validating the minor
     109number and arguments, this call reads the indicated device.  Most analog
     110devices store the last value written to a DAC.  Since DACs are output
     111only devices, saving the last written value gives the appearance that
     112DACs can be read from also.  If the device is an ADC, then it is sampled.
     113
     114@b{NOTE:} Many boards have multiple analog inputs but only one ADC.  On
     115these boards, it will be necessary to provide some type of mutual exclusion
     116during reads.  On these boards, there is a MUX which must be switched
     117before sampling the ADC.  After the MUX is switched, the driver must
     118delay some short period of time (usually microseconds) before the
     119signal is stable and can be sampled.  To make matters worse, some ADCs
     120cannot respond to wide voltage swings in a single sample.  On these
     121ADCs, one must do two samples when the voltage swing is too large.
     122On a practical basis, this means that the driver usually ends up
     123double sampling the ADC on these systems.
     124
     125The value returned is a single precision floating point number
     126representing the voltage read.  This value is stored in the
     127@code{argument_block} passed in to the call.  By returning the
     128voltage, the caller is freed from having to know the number of
     129bits in the analog and board dependent conversion algorithm.
     130
     131@section Write to a Particular Analog
     132
     133This corresponds to the driver write call.  After validating the minor
     134number and arguments, this call writes the indicated device.  If the
     135specified device is an ADC, then an error is usually returned. 
     136
     137The value written is a single precision floating point number
     138representing the voltage to be written to the specified DAC. 
     139This value is stored in the @code{argument_block} passed in to the
     140call.  By passing the voltage to the device driver, the caller is
     141freed from having to know the number of bits in the analog
     142and board dependent conversion algorithm.
     143
     144@section Reset DACs
     145
     146This is one of the IOCTL functions supported by the I/O control
     147device driver entry point.  When this IOCTL function is invoked,
     148all of the DACs are written to 0.0 volts.
     149
     150@section Reinitialize DACS
     151
     152This is one of the IOCTL functions supported by the I/O control
     153device driver entry point.  When this IOCTL function is invoked,
     154all of the DACs are written with the initial value configured
     155for this device.
     156
     157@section Get Last Written Values
     158
     159This is one of the IOCTL functions supported by the I/O control
     160device driver entry point.  When this IOCTL function is invoked,
     161the last value written to the specified output word along with
     162a timestamp of when the last write was performed.
     163
  • doc/bsp_howto/bsp_howto.texi

    r06fee20 rbc950e87  
    9090* Makefiles::
    9191* Linker Script::
    92 * Required Support Routines::
     92* Miscellaneous Support Files::
    9393* Initialization Code::
    9494* Console Driver::
  • doc/bsp_howto/clock.t

    r06fee20 rbc950e87  
    1111@section Introduction
    1212
    13 The clock driver aims at giving a steady time basis to the kernel, so that
    14 the RTEMS primitives that need a clock tick work properly. <insert a link
    15 to the Clock Driver defs>
     13The purpose of the clock driver is to provide a steady time
     14basis to the kernel, so that the RTEMS primitives that need
     15a clock tick work properly.  See the @code{Clock Manager} chapter
     16of the @b{RTEMS Application C User's Guide} for more details.
    1617
    17 The clock driver is located in the clock directory of the BSP.
     18The clock driver is located in the @code{clock} directory of the BSP.
    1819
    19 @section Primitives
     20@section Clock Driver Global Variables
    2021
    21 @subsection Initialization
     22@subsection Major and Minor Number
    2223
    23 The major and minor numbers of the clock driver can be made available to
    24 the others, such as the Shared Memory Driver.
     24The major and minor numbers of the clock driver are made available via
     25the following variables.
    2526
    26 Then you have to program your integrated processor periodic interval timer
    27 so that an interrupt is generated every m microseconds, where m =
    28 BSP_Configuration.microseconds_per_tick. Sometimes the periodic interval
     27@itemize @bullet
     28@item rtems_device_major_number rtems_clock_major;
     29@item rtems_device_minor_number rtems_clock_minor;
     30@end itemize
     31
     32The clock device driver is responsible for declaring and
     33initializing these variables.  These variables are used
     34by other RTEMS components -- notably the Shared Memory Driver.
     35
     36@b{NOTE:} In a future RTEMS version, these variables may be replaced
     37with the clock device driver registering @b{/dev/clock}.
     38
     39@subsection Ticks Counter
     40
     41Most of the clock device drivers provide a global variable
     42that is simply a count of the number of clock driver interrupt service
     43routines that have occured.  This information is valuable when debugging
     44a system.  This variable is declared as follows:
     45
     46@example
     47volatile rtems_unsigned32 Clock_driver_ticks;
     48@end example
     49
     50@section Initialization
     51
     52The initialization routine is responsible for
     53programming the hardware that will periodically
     54generate an interrupt.  A programmable interval timer is commonly
     55used as the source of the clock tick.
     56
     57The device should be programmed such that an interrupt is generated
     58every @i{m} microseconds, where @i{m} is equal to
     59@code{BSP_Configuration.microseconds_per_tick}. Sometimes the periodic interval
    2960timer can use a prescaler so you have to look carefully at your user's
    3061manual to determine the correct value.
    3162
    32 You must use the RTEMS primitive to put your clock interrupt routine in
    33 the VBR:
     63You must use the RTEMS primitive @code{rtems_interrupt_catch} to install
     64your clock interrupt service routine:
    3465
    3566@example
    36 rtems_interrupt_catch (InterruptHandler, CONSOLE_VECTOR, &old_handler);
     67rtems_interrupt_catch (Clock_ISR, CLOCK_VECTOR, &old_handler);
    3768@end example
    3869
    39 @subsection The Clock Interrupt Subroutine
     70Since there is currently not a driver entry point invoked at system
     71shutdown, many clock device drivers use the @code{atexit} routine
     72to schedule their @code{Clock_exit} routine to execute when the
     73system is shutdown.
     74
     75By convention, many of the clock drivers do not install the clock
     76tick if the @code{ticks_per_timeslice} field of the Configuration
     77Table is 0.
     78
     79@section System shutdown
     80
     81Many drivers provide the routine @code{Clock_exit} that is scheduled
     82to be run during system shutdown via the @code{atexit} routine.
     83The @code{Clock_exit} routine will disable the clock tick source
     84if it was enabled.  This can be used to prevent clock ticks after the
     85system is shutdown.
     86
     87@section Clock Interrupt Subroutine
    4088
    4189It only has to inform the kernel that a ticker has elapsed, so call :
    4290
    4391@example
    44 rtems_clock_tick();
     92@group
     93rtems_isr Clock_isr( rtems_vector_number vector )
     94@{
     95  invoke the rtems_clock_tick() directive to announce the tick
     96  if necessary for this hardware
     97    reload the programmable timer
     98@}
     99@end group
    45100@end example
    46101
     102@section IO Control
     103
     104The clock driver must supply a handler for the IO control device driver
     105entry point.  This functionality is used by other components -- notably
     106the Shared Memory Driver to install a wrapper for the clock interrupt
     107service routine.  The following shows the functionality required:
     108
     109@example
     110@group
     111rtems_device_driver Clock_control(
     112  rtems_device_major_number major,
     113  rtems_device_minor_number minor,
     114  void *pargp
     115)
     116@{
     117  error check the argument pointer parameter
     118
     119  if the command is "ISR"
     120    invoke the clock interrupt service routine
     121  else if the command is "NEW"
     122    install the requested handler
     123@}
     124@end group
     125@end example
     126
     127
     128
     129
  • doc/bsp_howto/console.t

    r06fee20 rbc950e87  
    1111@section Introduction
    1212
    13 This chapter describes how to do a console driver using RTEMS Termios
    14 support.
    15 
    16 The serial driver is called as soon as printf/scanf or read/write kind of
    17 input/output are needed. There are two main functioning modes:
     13This chapter describes the operation of a console driver using
     14the RTEMS POSIX Termios support.  Traditionally RTEMS has referred
     15to all serial device drivers as console device drivers.  A
     16console driver can be used to do raw data processing in addition
     17to the "normal" standard input and output device functions required
     18of a console.
     19
     20The serial driver may be called as the consequence of a C Library
     21call such as @code{printf} or @code{scanf} or directly via the
     22@code{read} or @code{write} system calls.
     23There are two main functioning modes:
    1824
    1925@itemize @bullet
    2026
    2127@item console: formatted input/output, with special characters (end of
    22 line, tabulations, etc...) recognition and processing,
     28line, tabulations, etc.) recognition and processing,
    2329
    2430@item raw: permits raw data processing.
     
    3137@section Termios
    3238
    33 Termios is a standard for terminal management, included in several Unix
    34 versions. Termios is good because:
    35 
    36 @itemize @bullet
    37 
    38 @item from the user's side: primitives to access the terminal and change
    39 configuration settings are the same under Unix and Rtems.
    40 
    41 @item from the BSP developer's side: it frees you from dealing with buffer
    42 states and mutual exclusions on them.
     39Termios is a standard for terminal management, included in the POSIX 1003.1b
     40standard.  It is commonly provided on UNIX implementations. 
     41Having RTEMS support for Termios is beneficial:
     42
     43@itemize @bullet
     44
     45@item from the user's side because it provides standard primitive operations
     46to access the terminal and change configuration settings.  These operations
     47are the same under Unix and Rtems.
     48
     49@item from the BSP developer's side because it frees the
     50developer from dealing with buffer states and mutual exclusions on them.
     51Early RTEMS console device drivers also did their own special
     52character processing.
    4353
    4454@end itemize
     
    5565@end itemize
    5666
    57 For more information on Termios, type man termios in your Unix box or go
    58 to http://www.freebsd.org/cgi/man.cgi.
     67At this time, RTEMS documentation does not include a thorough discussion
     68of the Termios functionality.  For more information on Termios,
     69type @code{man termios} on a Unix box or point a web browser
     70at
     71@ifset use-html
     72@href{http://www.freebsd.org/cgi/man.cgi,,,http://www.freebsd.org/cgi/man.cgi}.
     73@end ifset
     74@ifclear use-html
     75@code{http://www.freebsd.org/cgi/man.cgi}.
     76@end ifclear
    5977
    6078@section Driver Functioning Modes
     
    6583@itemize @bullet
    6684
    67 @item polling mode: the processor blocks on sending/receiving characters.
    68 This mode is not powerful, but is necessary when one wants to print an
    69 error message when the board hung. This is also the most simple mode to
    70 program,
    71 
    72 @item interrupt mode: the processor doesn't block on sending/receiving
    73 characters. Two buffers (one for the in-going characters, the others for
    74 the characters to be sent) are used. An interrupt is raised as soon as a
    75 character is in the UART. Then the int errupt subroutine insert the
    76 character at the input buffer queue. When a character is asked for input,
    77 this at the head of the buffer is returned. When characters have to be
    78 sent, one have to put the first characters (the number depends on the
    79 UART) in th e UART. Then an interrupt is raised when all the characters
    80 have been emitted. The interrupt subroutine has to send the characters
    81 remaining in the output buffer the same way.
    82 
    83 @end itemize
     85@item polled mode
     86@item interrupt driven mode
     87
     88@end itemize
     89
     90In polled mode, the processor blocks on sending/receiving characters.
     91This mode is not the most efficient way to utilize the UART. But
     92polled mode is usually necessary when one wants to print an
     93error message in the event of a fatal error such as al fatal error
     94in the BSP.  This is also the simplest mode to
     95program.  Polled mode is generally preferred if the serial port is
     96to be used primarily as a debug console.  In a simple polled driver,
     97the software will continuously check the status of the UART when
     98it is reading or writing to the UART.  Termios improves on this
     99by delaying the caller for 1 clock tick between successive checks
     100of the UART on a read operation.
     101
     102In interrupt driven mode, the processor does not block on sending/receiving
     103characters.  Data is buffered between the interrupt service routine
     104and application code.  Two buffers are used to insulate the application
     105from the relative slowness of the serial device.  One of the buffers is
     106used for incoming characters, while the other is used for outgoing characters.
     107
     108An interrupt is raised when a character is received by the UART.
     109The interrupt subroutine places the incoming character at the end
     110of the input buffer.  When an application asks for input,
     111the characters at the front of the buffer are returned.
     112
     113When the application prints to the serial device, the outgoing characters
     114are placed at the end of the output buffer.  The driver will place
     115one or more characters in the UART (the exact number depends on the UART)
     116An interrupt will be raised when all the characters have been transmitted.
     117The interrupt service routine has to send the characters
     118remaining in the output buffer the same way.   When the transmitting side
     119of the UART is idle, it is typically necessary to prime the transmitter
     120before the first interrupt will occur.
    84121
    85122@section Serial Driver Functioning Overview
    86123
    87 Figure 5 is an attempt of showing how a Termios driven serial driver works :
     124The following Figure shows how a Termios driven serial driver works:
     125
     126@example
     127This figure needs to be inserted in this document.
     128@end example
     129
     130The following list describes the basic flow.
    88131
    89132@itemize @bullet
     
    92135scanf, read, write, etc.),
    93136
    94 @item C library (in fact that's Cygnus Newlib) calls RTEMS procedure: glue
    95 is made in newlib*.c files which can be found under
    96 $RTEMS_ROOT/c/src/lib/libc directory,
    97 
    98 @item Glue code calls your serial driver entry routines.
     137@item C library (in fact that's Cygnus Newlib) calls RTEMS
     138system call interface. This code can be found in the
     139@code{c/src/lib/libc} directory.
     140
     141@item Glue code calls the serial driver entry routines.
    99142
    100143@end itemize
     
    102145@subsection Termios and Polled I/O
    103146
    104 You have to point Termios out which functions are used for simple
    105 character input/output:
    106 
    107 
    108 Function
    109 
    110 Description
    111 
    112 @example
     147The following functions are provided by the driver and invoked by
     148Termios for simple character input/output.  The specific names of
     149these routines are not important as Termios invokes them indirectly
     150via function pointers.
     151
     152@subsubsection pollWrite
     153
     154The @code{pollWrite} routine is responsible for writing @code{len} characters
     155from @code{buf} to the serial device specified by @code{minor}.
     156
     157@example
     158@group
    113159int pollWrite (int minor, const char *buf, int len)
    114 
    115 for (i=0; i<len; i++) @{
     160@{
     161  for (i=0; i<len; i++) @{
    116162     put buf[i] into the UART channel minor
    117163     wait for the character to be transmitted
    118164     on the serial line
     165  @}
    119166@}
    120 int pollread(int minor)
    121 @end example
    122 
    123 wait for a character to be available in the UART channel minor, then return it.
     167@end group
     168@end example
     169
     170@subsubsection pollRead
     171
     172The @code{pollRead} routine is responsible for reading a single character
     173from the serial device specified by @code{minor}.  If no character is
     174available, then the routine should return -1.
     175
     176@example
     177@group
     178int pollRead(int minor)
     179@{
     180   read status of UART
     181   if status indicates a character is available
     182     return character
     183   return -1
     184@}
     185@end group
     186@end example
    124187
    125188@subsection Termios and Interrupt Driven I/O
     
    127190The UART generally generates interrupts when it is ready to accept or to
    128191emit a number of characters. In this mode, the interrupt subroutine is the
    129 core of the driver:
    130 
    131 @example
     192core of the driver.
     193
     194@subsubsection InterruptHandler
     195
     196The @code{InterruptHandler} is responsible for processing asynchronous
     197interrupts from the UART.  There may be multiple interrupt handlers for
     198a single UART.  Some UARTs can generate a unique interrupt vector for
     199each interrupt source such as a character has been received or the
     200transmitter is ready for another character.
     201
     202In the simplest case, the @code{InterruptHandler} will have to check
     203the status of the UART and determine what caused the interrupt.
     204The following describes the operation of an @code{InterruptHandler}
     205which has to do this:
     206
     207@example
     208@group
    132209rtems_isr InterruptHandler (rtems_vector_number v)
    133 @end example
    134 
    135 check whether there was an error
    136 
    137 if some characters were received:
    138    ask Termios to put them on his input buffer
    139 
    140 if some characters have been transmitted (i.e. the UART output buffer is empty)
    141    tell TERMIOS that the characters have been
    142    transmitted. The TERMIOS routine will call
    143    the InterruptWrite function with the number
    144    of characters not transmitted yet if it is
    145    not zero.
     210@{
     211  check whether there was an error
     212
     213  if some characters were received:
     214     Ask Termios to put them on his input buffer
     215
     216  if some characters have been transmitted
     217        (i.e. the UART output buffer is empty)
     218     Tell TERMIOS that the characters have been
     219     transmitted. The TERMIOS routine will call
     220     the InterruptWrite function with the number
     221     of characters not transmitted yet if it is
     222     not zero.
     223@}
     224@end group
     225@end example
     226
     227@subsubsection InterruptWrite
     228
     229The @code{InterruptWrite} is responsible for telling the UART
     230that the @code{len} characters at @code{buf} are to be transmitted.
    146231
    147232@example
    148233static int InterruptWrite(int minor, const char *buf, int len)
    149 @end example
    150 
    151 you have to put the n first buf characters in the UART channel minor
    152 buffer (n is the UART channel size, n=1 on the MC68640). Generally, an
    153 interrupt is raised after these n characters being transmitted. So you may
    154 have to enable the UART interrupts after having put the characters in the
     234@{
     235   tell the UART to transmit len characters from buf
     236@}
     237@end example
     238
     239The driver has to put the @i{n} first buf characters in the UART channel minor
     240buffer (@i{n} is the UART channel size, @i{n}=1 on the MC68640). Generally, an
     241interrupt is raised after these @i{n} characters being transmitted. So
     242UART interrupts may have to be enabled after putting the characters in the
    155243UART.
    156244
    157245
    158 Figure 5: general TERMIOS driven serial driver functioning
    159 
    160246@subsection Initialization
    161247
    162 The driver initialization is called once during RTEMS initialization
     248The driver initialization is called once during the RTEMS initialization
    163249process.
    164250
    165 The console_initialize function has to :
    166 
    167 @itemize @bullet
    168 
    169 @item initialize Termios support: call rtems_termios_initialize(),
    170 
    171 @item initialize your integrated processor's UART: the operation is
    172 normally described in your user's manual and you must follow these
    173 instructions but it usually consists in:
    174 
    175 @item reinitialize the UART channels,
    176 
    177 @item set the channels configuration to Termios default one, i.e.: 9600
    178 bauds, no parity, 1 stop bit, 8 bits per character,
    179 
    180 @item register your console interrupt routine to RTEMS:
     251The @code{console_initialize} function has to:
     252
     253@itemize @bullet
     254
     255@item initialize Termios support: call @code{rtems_termios_initialize()}.  If
     256Termios has already been initialized by another device driver, then
     257this call will have no effect.
     258
     259@item Initialize the UART: This procedure should
     260be described in the UART manual.  This procedure @b{MUST} be
     261followed precisely.  This procedure varies but
     262usually consists of:
     263
     264@itemize @bullet
     265@item reinitialize the UART channels
     266
     267@item set the channels configuration to the Termios default:
     2689600 bauds, no parity, 1 stop bit, and 8 bits per character
     269@end itemize
     270
     271@item If interrupt driven, register the console interrupt routine to RTEMS:
    181272
    182273@example
     
    184275@end example
    185276
    186 @item enable the UART channels,
    187 
    188 @item register your device name: in order to use the console (i.e. being
    189 able to do printf/scanf on stdin, stdout, and stderr), you have to
    190 register the "/dev/console" device:
     277@item enable the UART channels.
     278
     279@item register the device name: in order to use the console (i.e. being
     280able to do printf/scanf on stdin, stdout, and stderr), some device
     281must be registered as "/dev/console":
    191282
    192283@example
     
    198289@subsection Opening a serial device
    199290
    200 The console device is opened during RTEMS initialization but the
    201 console_open function is called when a new device is opened. For instance,
    202 if you register the "/dev/tty1" device for the UART channel 2, the
    203 console_open will be called with a fopen("/dev/t ty", mode) in your
     291The @code{console_open} function is called whenever a serial
     292device is opened.  The device registered as @code{"/dev/console"}
     293is opened automatically during RTEMS initialization.
     294For instance, if UART channel 2 is registered as "/dev/tty1",
     295the @code{console_open} entry point will be called as
     296the result of an @code{fopen("/dev/tty1", mode)} in the
    204297application.
    205298
    206 The console_open function has to inform Termios of your low-level function
    207 for serial line support; the "callbacks".
    208 
    209 The gen68340 BSP defines two kinds of callbacks:
    210 
    211 @itemize @bullet
    212 
    213 @item functions to use with polled input/output,
    214 
    215 @item functions to use with interrupt input/output.
    216 
    217 @end itemize
     299The @code{console_open} function has to inform Termios of the low-level
     300functions for serial line support; the "callbacks".
     301
     302The gen68340 BSP defines two sets of callback tables:
     303
     304@itemize @bullet
     305
     306@item one with functions for polled input/output
     307
     308@item another with functions for interrupt driven input/output
     309
     310@end itemize
     311
     312This code can be found in the file @code{$BSPROOT/console/console.c}.
    218313
    219314@subsubsection Polled I/O
    220315
    221 You have to point Termios out which functions are used for simple
    222 character input/output, i.e. pointers to pollWrite and pollRead functions
    223 defined in 8.4.1.
     316Termios must be told the addresses of the functions that are to be
     317used for simple character input/output, i.e. pointers to the
     318@code{pollWrite} and @code{pollRead} functions
     319defined earlier in @ref{Console Driver Termios and Polled I/O}.
    224320
    225321@subsubsection Interrupt Driven I/O
    226322
    227 Driver functioning is quite different in this mode. You can see there's no
    228 read function passed to Termios. Indeed a console_read call returns the
    229 content of Termios input buffer. This buffer is filled in the driver
    230 interrupt subroutine (cf. 8.4.2).
    231 
    232 But you actually have to provide a pointer to the InterruptWrite function.
    233 
    234 @subsection Closing a serial device
    235 
    236 The driver entry point is: console_close.
    237 
    238 You just have to notify Termios that the serial device was closed, with a
    239 call to rtems_termios_close.
    240 
    241 @subsection Reading characters from the serial device
    242 
    243 The driver entry point is: console_read.
    244 
    245 You just have to return the content of the Termios input buffer.
    246 
    247 Call rtems_termios_read.
    248 
    249 @subsection Writing characters to the serial device
    250 
    251 The driver entry point is: console_write.
    252 
    253 You just have to add the characters at the end of the Termios output
     323Driver functioning is quite different in this mode.  There is no
     324device driver read function to be passed to Termios. Indeed a
     325@code{console_read} call returns the contents of Termios input buffer.
     326This buffer is filled in the driver interrupt subroutine
     327(see @ref{Console Driver Termios and Interrupt Driven I/O}).
     328
     329The driver is responsible for providing a pointer to the
     330@code{InterruptWrite} function.
     331
     332@subsection Closing a Serial Device
     333
     334The @code{console_close} is invoked when the serial device is to
     335be closed.  This entry point corresponds to the device driver
     336close entry point.
     337
     338This routine is responsible for notifying Termios that the serial
     339device was closed.  This is done with a call to @code{rtems_termios_close}.
     340
     341@subsection Reading Characters From a Serial Device
     342
     343The @code{console_read} is invoked when the serial device is to
     344be read from.  This entry point corresponds to the device driver
     345read entry point.
     346
     347This routine is responsible for returning the content of the
     348Termios input buffer.   This is done by invoking the
     349@code{rtems_termios_read} routine.
     350
     351@subsection Writing Characters to a Serial Device
     352
     353The @code{console_write} is invoked when the serial device is to
     354be written to.  This entry point corresponds to the device driver
     355write entry point.
     356
     357This routine is responsible for adding the requested characters to
     358the Termios output queue for this device.  This is done by
     359calling the routine @code{rtems_termios_write}
     360to add the characters at the end of the Termios output
    254361buffer.
    255362
    256 Call rtems_termios_write.
    257 
    258 @subsection Changing serial line parameters
    259 
    260 The driver entry point is: console_control.
     363@subsection Changing Serial Line Parameters
     364
     365The @code{console_control} is invoked when the line parameters
     366for a particular serial device are to be changed.
     367This entry point corresponds to the device driver
     368io_control entry point.
    261369
    262370The application write is able to control the serial line configuration
    263 with Termios calls (such as the ioctl command, see Termios man page for
    264 more details). If you want to support dynamic configuration, you have to
    265 write the console_control piece of code . Look at the gen68340 BSP for an
    266 example of how it is done. Basically ioctl commands call console_control
    267 with the serial line configuration in a Termios structure. You just have
    268 to reinitialize the UART with the correct settings.
    269 
     371with Termios calls (such as the @code{ioctl} command, see
     372the Termios documentation for
     373more details). If the driver is to support dynamic configuration, then
     374is must have the @code{console_control} piece of code. Refer to the gen68340
     375BSP for an example of how it is done.  Basically @code{ioctl}
     376commands call @code{console_control} with the serial line
     377configuration in a Termios defined data structure. The driver
     378is responsible for reinitializing the UART with the correct settings.
     379
  • doc/bsp_howto/discrete.t

    r06fee20 rbc950e87  
    99@chapter Discrete Driver
    1010
    11 XXX FILL ME IN
     11The Discrete driver is responsible for providing an
     12interface to Discrete Input/Outputs.  The capabilities provided
     13by this class of device driver are:
    1214
     15@itemize @bullet
     16@item Initialize a Discrete I/O Board
     17@item Open a Particular Discrete Bitfield
     18@item Close a Particular Discrete Bitfield
     19@item Read from a Particular Discrete Bitfield
     20@item Write to a Particular Discrete Bitfield
     21@item Reset DACs
     22@item Reinitialize DACS
     23@end itemize
     24
     25Most discrete I/O devices are found on I/O cards that support many
     26bits of discrete I/O on a single card.  This driver model is centered
     27on the notion of reading bitfields from the card.
     28
     29There are currently no discrete I/O device drivers included in the
     30RTEMS source tree.  The information provided in this chapter
     31is based on drivers developed by OAR Corporation personnel
     32for applications using RTEMS.   It is hoped that this
     33driver model information can form the basis for a standard
     34discrete I/O driver model that can be supported in future RTEMS
     35distribution.
     36
     37@section Major and Minor Numbers
     38
     39The @b{major} number of a device driver is its index in the
     40RTEMS Device Address Table.
     41
     42A @b{minor} number is associated with each device instance
     43managed by a particular device driver.  An RTEMS minor number
     44is an @code{unsigned32} entity.  Convention calls for
     45dividing the bits in the minor number down into categories
     46that specify a particular bitfield.  This results in categories
     47like the following:
     48
     49@itemize @bullet
     50
     51@item @b{board} - indicates the board a particular bitfield is located on
     52@item @b{word} - indicates the particular word of discrete bits the
     53bitfield is located within
     54@item @b{start} - indicates the starting bit of the bitfield
     55@item @b{width} - indicates the width of the bitfield
     56
     57@end itemize
     58
     59From the above, it should be clear that a single device driver
     60can support multiple copies of the same board in a single system.
     61The minor number is used to distinguish the devices.
     62
     63By providing a way to easily access a particular bitfield from
     64the device driver, the application is insulated with knowing how
     65to mask fields in and out of a discrete I/O.
     66
     67@section Discrete I/O Driver Configuration
     68
     69There is not a standard discrete I/O driver configuration table but some
     70fields are common across different drivers.  The discrete I/O driver
     71configuration table is typically an array of structures with each
     72structure containing the information for a particular board.
     73The following is a list of the type of information normally required
     74to configure an discrete I/O board:
     75
     76@table @b
     77@item board_offset
     78is the base address of a board.
     79
     80@item relay_initial_values
     81is an array of the values that should be written to each output
     82word on the board during initialization.  This allows the driver
     83to start with the board's output  in a known state.
     84
     85@end table
     86
     87@section Initialize a Discrete I/O Board
     88
     89At system initialization, the discrete I/O driver's initialization entry point
     90will be invoked.  As part of initialization, the driver will perform
     91whatever board initializatin is required and then set all
     92outputs to their configured initial state.
     93
     94The discrete I/O driver may register a device name for bitfields of
     95particular interest to the system.  Normally this will be restricted
     96to the names of each word and, if the driver supports it, an "all words".
     97
     98@section Open a Particular Discrete Bitfield
     99
     100This is the driver open call.  Usually this call does nothing other than
     101validate the minor number. 
     102
     103With some drivers, it may be necessary to allocate memory when a particular
     104device is opened.  If that is the case, then this is often the place
     105to do this operation.
     106
     107@section Close a Particular Discrete Bitfield
     108
     109This is the driver close call.  Usually this call does nothing.
     110
     111With some drivers, it may be necessary to allocate memory when a particular
     112device is opened.  If that is the case, then this is the place
     113where that memory should be deallocated.
     114
     115@section Read from a Particular Discrete Bitfield
     116
     117This corresponds to the driver read call.  After validating the minor
     118number and arguments, this call reads the indicated bitfield.  A
     119discrete I/O devices may have to store the last value written to
     120a discrete output.  If the bitfield is output only, saving the last
     121written value gives the appearance that it can be read from also. 
     122If the bitfield is input, then it is sampled.
     123
     124@b{NOTE:} Many discrete inputs have a tendency to bounce.  The application
     125may have to take account for bounces.
     126
     127The value returned is an @code{unsigned32} number
     128representing the bitfield read.  This value is stored in the
     129@code{argument_block} passed in to the call.
     130
     131@b{NOTE:} Some discrete I/O drivers have a special minor number
     132used to access all discrete I/O bits on the board.  If this special
     133minor is used, then the area pointed to by @code{argument_block} must
     134be the correct size.
     135
     136@section Write to a Particular Discrete Bitfield
     137
     138This corresponds to the driver write call.  After validating the minor
     139number and arguments, this call writes the indicated device.  If the
     140specified device is an ADC, then an error is usually returned. 
     141
     142The value written is an @code{unsigned32} number
     143representing the value to be written to the specified
     144bitfield.  This value is stored in the
     145@code{argument_block} passed in to the call.
     146
     147@b{NOTE:} Some discrete I/O drivers have a special minor number
     148used to access all discrete I/O bits on the board.  If this special
     149minor is used, then the area pointed to by @code{argument_block} must
     150be the correct size.
     151
     152@section Disable Discrete Outputs
     153
     154This is one of the IOCTL functions supported by the I/O control
     155device driver entry point.  When this IOCTL function is invoked,
     156the discrete outputs are disabled.
     157
     158@b{NOTE:} It may not be possible to disable/enable discrete output on all
     159discrete I/O boards.
     160
     161@section Enable Discrete Outputs
     162
     163This is one of the IOCTL functions supported by the I/O control
     164device driver entry point.  When this IOCTL function is invoked,
     165the discrete outputs are enabled.
     166
     167@b{NOTE:} It may not be possible to disable/enable discrete output on all
     168discrete I/O boards.
     169
     170@section Reinitialize Outputs
     171
     172This is one of the IOCTL functions supported by the I/O control
     173device driver entry point.  When this IOCTL function is invoked,
     174the discrete outputs are rewritten with the configured initial
     175output values.
     176
     177@section Get Last Written Values
     178
     179This is one of the IOCTL functions supported by the I/O control
     180device driver entry point.  When this IOCTL function is invoked,
     181the last value written to the specified output word along with
     182a timestamp of when the last write was performed.
     183
  • doc/bsp_howto/init.t

    r06fee20 rbc950e87  
    2222initialization code.  Like most BSPs, the initialization for this
    2323BSP is divided into two subdirectories under the BSP source directory.
    24 The gen68340 BSP source code in the following directory:
    25 
    26 @example
    27 c/src/lib/libbsp/m68k/gen68340:
    28 @end example
     24The gen68340 BSP source code is in the following directory:
     25
     26@example
     27c/src/lib/libbsp/m68k/gen68340
     28@end example
     29
     30The following source code files are in this subdirectory.
    2931
    3032@itemize @bullet
     
    4648contains initialization for a 68349 based board as well.
    4749
     50@section Required Global Variables
     51
     52Although not strictly part of initialization, there are a few global
     53variables assumed to exist by many support components.  These
     54global variables are usually declared in the file @code{startup/bspstart.c}
     55that provides most of the BSP specific initialization.  The following is
     56a list of these global variables:
     57
     58@itemize @bullet
     59@item @code{BSP_Configuration} is the BSP's writable copy of the RTEMS
     60Configuration Table.
     61
     62@item @code{Cpu_table} is the RTEMS CPU Dependent Information Table.
     63
     64@item @code{bsp_isr_level} is the interrupt level that is set at
     65system startup.  It will be restored when the executive returns
     66control to the BSP.
     67
     68@end itemize
     69
    4870@section Board Initialization
    4971
     
    7799
    78100The @code{boot_card()} is the first C code invoked.  Most of the BSPs
    79 use the sams shared version of @code{boot_card()} which is located in
     101use the same shared version of @code{boot_card()} which is located in
    80102the following file:
    81103
     
    129151This routine is also responsible for overriding the default settings
    130152in the CPU Configuration Table and setting port specific entries
    131 in this table.  This routine will typically install routines
    132 for one or more of the following initialization hooks:
     153in this table.  This may include increasing the maximum number
     154of some types of RTEMS system objects to reflect the needs of
     155the BSP and the base set of device drivers. This routine will
     156typically also install routines for one or more of the following
     157initialization hooks:
    133158
    134159@itemize @bullet
     
    173198
    174199In addition to the implicit invocation of @code{__main}, this
    175 routine performs some explitit initialization.  This routine
     200routine performs some explicit initialization.  This routine
    176201sets the variable @code{rtems_progname} and initiates
    177202multitasking via a call to the RTEMS directive
     
    180205RTEMS directive @code{rtems_shutdown_executive} is invoked.
    181206
     207The RTEMS initialization procedure is described in the @b{Initialization
     208Manager} chapter of the @b{RTEMS Application C User's Guide}.
     209Please refer to that manual for more information.
     210
    182211@subsection RTEMS Pretasking Callback
    183212
    184213The @code{pretasking_hook} entry in the RTEMS CPU Configuration
    185214Table may be the address of a user provided routine that is
    186 invoked once RTEMS initialization is complete but before interrupts
     215invoked once RTEMS API initialization is complete but before interrupts
    187216and tasking are enabled.  No tasks -- not even the IDLE task -- have
    188217been created when this hook is invoked.  The pretasking hook is optional.
     
    198227The @code{bsp_pretasking_hook()} routine is the appropriate place to
    199228initialize any support components which depend on the RTEMS APIs.
    200 Most BSPs initialize the RTEMS C Library support in their
     229Most BSPs set the debug level for the system and initialize the
     230RTEMS C Library support in their
    201231implementation of @code{bsp_pretasking_hook()}.  This initialization
    202 includes the application heap as well as the reentrancy support
    203 for the C Library.
     232includes the application heap used by the @code{malloc} family
     233of routines as well as the reentrancy support for the C Library.
     234
     235The routine @code{bsp_libc_init} routine invoked from the
     236@code{bsp_pretasking_hook()} routine is passed the starting
     237address, length, and growth amount passed to @code{sbrk}. 
     238This "sbrk amount" is only used if the heap runs out of
     239memory.  In this case, the RTEMS malloc implementation will
     240invoked @code{sbrk} to obtain more memory.  See
     241@ref{Miscellaneous Support Files sbrk() Implementation} for more details.
    204242
    205243@subsection RTEMS Predriver Callback
    206244
    207 XXX is the address of the user provided
    208 routine which is invoked with tasking enabled immediately before
    209 the MPCI and device drivers are initialized. RTEMS
    210 initialization is complete, interrupts and tasking are enabled,
    211 but no device drivers are initialized.  This field may be NULL to
    212 indicate that the hook is not utilized.
     245The @code{predriver_hook} entry in the RTEMS CPU Configuration
     246Table may be the address of a user provided routine that is
     247is invoked immediately before the the device drivers and MPCI
     248are initialized. RTEMS
     249initialization is complete but interrupts and tasking are disabled.
     250This field may be NULL to indicate that the hook is not utilized.
     251
     252Most BSPs do not use this callback.
    213253
    214254@subsection Device Driver Initialization
     
    216256At this point in the initialization sequence, the initialization
    217257routines for all of the device drivers specified in the Device
    218 Driver Table are invoked.
     258Driver Table are invoked.  The initialization routines are invoked
     259in the order they appear in the Device Driver Table.
     260
     261The Driver Address Table is part of the RTEMS Configuration Table. It
     262defines device drivers entry points (initialization, open, close, read,
     263write, and control). For more information about this table, please
     264refer to the @b{Configuring a System} chapter in the
     265@b{RTEMS Application C User's Guide}.
     266
     267The RTEMS initialization procedure calls the initialization function for
     268every driver defined in the RTEMS Configuration Table (this allows
     269one to include only the drivers needed by the application).
     270
     271All these primitives have a major and a minor number as arguments:
     272
     273@itemize @bullet
     274
     275@item the major number refers to the driver type,
     276
     277@item the minor number is used to control two peripherals with the same
     278driver (for instance, we define only one major number for the serial
     279driver, but two minor numbers for channel A and B if there are two
     280channels in the UART).
     281
     282@end itemize
    219283
    220284@subsection RTEMS Postdriver Callback
    221285
    222 XXX is the address of the user provided
    223 routine which is invoked with tasking enabled immediately after
    224 the MPCI and device drivers are initialized. RTEMS
    225 initialization is complete, interrupts and tasking are enabled,
    226 and the device drivers are initialized.  This field may be NULL
    227 to indicate that the hook is not utilized.
    228 
    229 
    230 @section The Interrupts Vector Table
    231 
    232 
    233 
    234 After the entry label starts a code section in which some room is
    235 allocated for the table of interrupts vectors. They are assigned to the
    236 address of the __uhoh label.
    237 
    238 At __uhoh label you can find the default interrupt handler routine. This
    239 routine is only called when an unexpected interrupts is raised. You can
    240 add your own routine there (in that case there's a call to a routine -
    241 $BSP_ROOT/startup/dumpanic.c - that pri nts which address caused the
    242 interrupt and the contents of the registers, stack...), but this should
     286The @code{postdriver_hook} entry in the RTEMS CPU Configuration
     287Table may be the address of a user provided routine that is
     288invoked immediately after the the device drivers and MPCI are initialized.
     289Interrupts and tasking are disabled.  The postdriver hook is optional.
     290
     291Although optional, most of the RTEMS BSPs provide a postdriver hook
     292callback.  This routine is usually called @code{bsp_postdriver_hook}
     293and is found in the file:
     294
     295@example
     296c/src/lib/libbsp/CPU/BSP/startup/bsppost.c
     297@end example
     298
     299The @code{bsp_postdriver_hook()} routine is the appropriate place to
     300perform initialization that must be performed before the first task
     301executes but requires that a device driver be initialized.  The
     302shared implementation of the postdriver hook opens the default
     303standard in, out, and error files and associates them with
     304@code{/dev/console}.
     305
     306@section The Interrupt Vector Table
     307
     308The Interrupt Vector Table is called different things on different
     309processor families but the basic functionality is the same.  Each
     310entry in the Table corresponds to the handler routine for a particular
     311interrupt source.  When an interrupt from that source occurs, the
     312specified handler routine is invoked.  Some context information is
     313saved by the processor automatically when this happens.  RTEMS saves
     314enough context information so that an interrupt service routine
     315can be implemented in a high level language.
     316
     317On some processors, the Interrupt Vector Table is at a fixed address.  If
     318this address is in RAM, then usually the BSP only has to initialize
     319it to contain pointers to default handlers.  If the table is in ROM,
     320then the application developer will have to take special steps to
     321fill in the table.
     322
     323If the base address of the Interrupt Vector Table can be dynamically
     324changed to an arbitrary address, then the RTEMS port to that processor
     325family will usually allocate its own table and install it.  For example,
     326on some members of the Motorola MC68xxx family, the Vector Base Register
     327(@code{vbr}) contains this base address. 
     328
     329@subsection Interrupt Vector Table on the gen68340 BSP
     330
     331The gen68340 BSP provides a default Interrupt Vector Table in the
     332file @code{$BSP_ROOT/start340/start340.s}.  After the @code{entry}
     333label is the definition of space reserved for the table of
     334interrupts vectors.  This space is assigned the symbolic name
     335of @code{__uhoh} in the @code{gen68340} BSP.
     336
     337At @code{__uhoh} label is the default interrupt handler routine. This
     338routine is only called when an unexpected interrupts is raised.  One can
     339add their own routine there (in that case there's a call to a routine -
     340$BSP_ROOT/startup/dumpanic.c - that prints which address caused the
     341interrupt and the contents of the registers, stack, etc.), but this should
    243342not return.
    244343
     
    246345
    247346When the microprocessor accesses a memory area, address decoding is
    248 handled by an address decoder (!), so that the microprocessor knows which
    249 memory chip to access.
    250 
    251 Figure 4 : address decoding
    252 
    253 You have to program your Chip Select registers in order that they match
    254 the linkcmds settings. In this BSP ROM and RAM addresses can be found in
    255 both the linkcmds and initialization code, but this is not a great way to
    256 do, better use some shared variables .
    257 
    258 @section Integrated processor registers initialization
    259 
    260 There are always some specific integrated processor registers
    261 initialization to do. Integrated processors' user manuals often detail
    262 them.
    263 
    264 @section Data section recopy
     347handled by an address decoder, so that the microprocessor knows which
     348memory chip(s) to access.   The following figure illustrates this:
     349
     350@example
     351@group
     352                     +-------------------+
     353         ------------|                   |
     354         ------------|                   |------------
     355         ------------|      Address      |------------
     356         ------------|      Decoder      |------------
     357         ------------|                   |------------
     358         ------------|                   |
     359                     +-------------------+
     360           CPU Bus                           Chip Select
     361@end group
     362@end example
     363
     364
     365The Chip Select registers must be programmed such that they match
     366the @code{linkcmds} settings. In the gen68340 BSP, ROM and RAM
     367addresses can be found in both the @code{linkcmds} and initialization
     368code, but this is not a great way to do this.  It is better to
     369define addresses in the linker script.
     370
     371@section Integrated Processor Registers Initialization
     372
     373The CPUs used in many embedded systems are highly complex devices
     374with multiple peripherals on the CPU itself.  For these devices,
     375there are always some specific integrated processor registers
     376that must be initialized.  Refer to the processors' manuals for
     377details on these registers and be VERY careful programming them.
     378
     379@section Data Section Recopy
    265380
    266381The next initialization part can be found in
    267 $BSP340_ROOT/start340/init68340.c. First the Interrupt Vector Table is
    268 copied into RAM, then the data section recopy is initiated
    269 (_CopyDataClearBSSAndStart in $BSP340_ROOT/start340/startfor340only.s).
     382@code{$BSP340_ROOT/start340/init68340.c}. First the Interrupt
     383Vector Table is copied into RAM, then the data section recopy is initiated
     384(_CopyDataClearBSSAndStart in @code{$BSP340_ROOT/start340/startfor340only.s}).
    270385
    271386This code performs the following actions:
     
    274389
    275390@item copies the .data section from ROM to its location reserved in RAM
    276 (see 5.2 for more details about this copy),
    277 
    278 @item clear .bss section (all the non-initialized data will take value 0).
    279 
    280 @end itemize
    281 
    282 Then control is passed to the RTEMS-specific initialization code.
     391(see @ref{Linker Script Initialized Data} for more details about this copy),
     392
     393@item clear @code{.bss} section (all the non-initialized
     394data will take value 0).
     395
     396@end itemize
    283397
    284398@section RTEMS-Specific Initialization
     
    291405structures.
    292406
    293 The RTEMS configuration table is application dependant, which means that
    294 one has to provide one per application. It's usually an header file
    295 included in the main module of the application.
    296 
    297 The BSP_Configuration label points on this table.
    298 
    299 For more information on the RTEMS configuration table, refer to C user's
    300 guide, chapter 23 <insert a link here>.
    301 
    302 @section RTEMS initialization procedure
    303 
    304 The RTEMS initialization procedure is described in the 3rd chapter of the
    305 C user's manual <insert a link here>. Please read it carefully.
    306 
    307 There are a few BSP specific functions called from the initialization
    308 manager. They can be found in the startup directory of the BSP.
    309 
    310 @table @b
    311 
    312 @item bspstart.c
    313 
    314 It starts the application.  It includes application, board, and monitor
    315 specific initialization and configuration.
    316 
    317 @item bspstart.c
    318 
    319 @table @b
    320 @item bsp_pretasking_hook
    321 
    322 It starts libc support (needed to allocate some memory using C primitive
    323 malloc for example). Heap size must be passed in argument, this is the one
    324 which is defined in the linkcmds (cf. 5.)
    325 
    326 
    327 @end table
    328 
    329 @item bspclean.c
    330 
    331 @table @b
    332 
    333 @item bsp_cleanup
    334 
    335 Return control to the monitor.
    336 
    337 @end table
    338 
    339 @end table
    340 
    341 @section Drivers initialization
    342 
    343 The Driver Address Table is part of the RTEMS configuration table. It
    344 defines RTEMS drivers entry points (initialization, open, close, read,
    345 write, and control). For more information about this table, check C User's
    346 manual chapter 21 section 6 <insert a l ink here>.
    347 
    348 The RTEMS initialization procedure calls the initialization function for
    349 every driver defined in the RTEMS Configuration Table (this permits to add
    350 only the drivers needed by the application).
    351 
    352 All these primitives have a major and a minor number as arguments:
    353 
    354 @itemize @bullet
    355 
    356 @item the major number refers to the driver type,
    357 
    358 @item the minor number is used to control two peripherals with the same
    359 driver (for instance, we define only one major number for the serial
    360 driver, but two minor numbers for channel A and B if there are two
    361 channels in the UART).
    362 
    363 @end itemize
    364 
     407The RTEMS configuration table is application dependent, which means that
     408one has to provide one per application. It is usually defined
     409by defining macros and including the header file @code{<confdefs.h>}.
     410In simple applications such as the tests provided with RTEMS, it is
     411commonly found in the main module of the application.  For more complex
     412applications, it may be in a file by itself.
     413
     414The header file @code{<confdefs.h>} defines a constant table named
     415@code{Configuration}.  It is common practice for the BSP to copy
     416this table into a modifiable copy named @code{BSP_Configuration}.
     417This copy of the table is modified to define the base address of the
     418RTEMS Executive Workspace as well as to reflect any BSP and
     419device driver requirements not automatically handled by the application.
     420
     421For more information on the RTEMS Configuration Table, refer to the
     422@b{RTEMS Application C User's Guide}.
     423
  • doc/bsp_howto/network.t

    r06fee20 rbc950e87  
    1 @c
    2 @c  COPYRIGHT (c) 1988-1998.
    3 @c  On-Line Applications Research Corporation (OAR).
    4 @c  All rights reserved.
    5 @c
    6 @c  $Id$
    7 @c
    8 
    9 @chapter Networking Driver
    10 
    11 XXX FILL ME IN
    12 
  • doc/bsp_howto/nvmem.t

    r06fee20 rbc950e87  
    99@chapter Non-Volatile Memory Driver
    1010
    11 XXX FILL ME IN
    12 
     11The Non-Volatile driver is responsible for providing an
     12interface to various types of non-volatile memory.  These
     13types of memory include, but are not limited to, Flash, EEPROM,
     14and battery backed RAM.  The capabilities provided
     15by this class of device driver are:
     16
     17@itemize @bullet
     18@item Initialize the Non-Volatile Memory Driver
     19@item Optional Disable Read and Write Handlers
     20@item Open a Particular Memory Partition
     21@item Close a Particular Memory Partition
     22@item Read from a Particular Memory Partition
     23@item Write to a Particular Memory Partition
     24@item Erase the Non-Volatile Memory Area
     25@end itemize
     26
     27There is currently only one non-volatile device driver included in the
     28RTEMS source tree and it does not adhere to this device driver model. 
     29The information provided in this chapter is based on drivers developed
     30by OAR Corporation personnel for applications using RTEMS.   It is
     31hoped that this driver model information can form the basis for a standard
     32non-volatile memory driver model that can be supported in future RTEMS
     33distribution.
     34
     35@section Major and Minor Numbers
     36
     37The @b{major} number of a device driver is its index in the
     38RTEMS Device Address Table.
     39
     40A @b{minor} number is associated with each device instance
     41managed by a particular device driver.  An RTEMS minor number
     42is an @code{unsigned32} entity.  Convention calls
     43dividing the bits in the minor number down into categories
     44that specify an area of non-volatile memory and a partition
     45with that area.  This results in categories
     46like the following:
     47
     48@itemize @bullet
     49
     50@item @b{area} - indicates a block of non-volatile memory
     51@item @b{partition} - indicates a particular address range with an area
     52
     53@end itemize
     54
     55From the above, it should be clear that a single device driver
     56can support multiple types of non-volatile memory in a single system.
     57The minor number is used to distinguish the types of memory and
     58blocks of memory used for different purposes.
     59
     60@section Non-Volatile Memory Driver Configuration
     61
     62There is not a standard non-volatile driver configuration table but some
     63fields are common across different drivers.  The non-volatile memory driver
     64configuration table is typically an array of structures with each
     65structure containing the information for a particular area of
     66non-volatile memory.
     67The following is a list of the type of information normally required
     68to configure each area of non-volatile memory
     69
     70@table @b
     71@item memory_type
     72is the type of memory device in this area.  Choices are battery backed RAM,
     73EEPROM, Flash, or an optional user-supplied type.  If the user-supplied type
     74is configured, then the user is responsible for providing a set of
     75routines to program the memory.
     76
     77@item memory
     78is the base address of this memory area.
     79
     80@item attributes
     81is a pointer to a memory type specific attribute block.  Some of
     82the fields commonly contained in this memory type specific attribute
     83structure area:
     84
     85@table @b
     86@item use_protection_algorithm
     87is set to TRUE to indicate that the protection (i.e. locking) algorithm
     88should be used for this area of non-volatile memory.  A particular
     89type of non-volatile memory may not have a protection algorithm.
     90
     91@item access
     92is an enumerated type to indicate the organization of the memory
     93devices in this memory area.  The following is a list of the
     94access types supported by the current driver implementation:
     95
     96@itemize @bullet
     97@item simple unsigned8
     98@item simple unsigned16
     99@item simple unsigned32
     100@item simple unsigned64
     101@item single unsigned8 at offset 0 in an unsigned16
     102@item single unsigned8 at offset 1 in an unsigned16
     103@item single unsigned8 at offset 0 in an unsigned32
     104@item single unsigned8 at offset 1 in an unsigned32
     105@item single unsigned8 at offset 2 in an unsigned32
     106@item single unsigned8 at offset 3 in an unsigned32
     107@end itemize
     108
     109@item depth
     110is the depth of the progamming FIFO on this particular chip.  Some
     111chips, particularly EEPROMs, have the same programming algorithm but
     112vary in the depth of the amount of data that can be programmed in a single
     113block.
     114
     115@end table
     116
     117@item number_of_partitions
     118is the number of logical partitions within this area.
     119
     120@item Partitions
     121is the address of table that contains an entry to describe each
     122partition in this area.  Fields within each element of this
     123table are defined as follows:
     124
     125@table @b
     126
     127@item offset
     128is the offset of this partition from the base address of this area.
     129
     130@item length
     131is the length of this partition.
     132
     133@end table
     134@end table
     135
     136By dividing an area of memory into multiple partitions, it is possible
     137to easily divide the non-volatile memory for different purposes.
     138
     139@section Initialize the Non-Volatile Memory Driver
     140
     141At system initialization, the non-volatile memory driver's
     142initialization entry point will be invoked.  As part of
     143initialization, the driver will perform
     144whatever initializatin is required on each non-volatile memory area.
     145
     146The discrete I/O driver may register devices name for memory
     147partitions of particular interest to the system.  Normally this
     148will be restricted to the device "/dev/nv_memory" to indicate
     149the entire device driver.
     150
     151@section Disable Read and Write Handlers
     152
     153Depending on the target's non-volatile memory configuration, it may be
     154possible to write to a status register and make the memory area completely
     155inaccessible.  This is target dependent and beyond the standard capabilities
     156of any memory type.  The user has the optional capability to provide
     157handlers to disable and enable access to a partiticular memory area.
     158
     159@section Open a Particular Memory Partition
     160
     161This is the driver open call.  Usually this call does nothing other than
     162validate the minor number.
     163
     164With some drivers, it may be necessary to allocate memory when a particular
     165device is opened.  If that is the case, then this is often the place
     166to do this operation.
     167
     168@section Close a Particular Memory Partition
     169
     170This is the driver close call.  Usually this call does nothing.
     171
     172With some drivers, it may be necessary to allocate memory when a particular
     173device is opened.  If that is the case, then this is the place
     174where that memory should be deallocated.
     175
     176@section Read from a Particular Memory Partition
     177
     178This corresponds to the driver read call.  After validating the minor
     179number and arguments, this call enables reads from the specified
     180memory area by invoking the user supplied "enable reads handler"
     181and then reads the indicated memory area.  When
     182invoked the @code{argument_block} is actually a pointer to the following
     183structure type:
     184
     185@example
     186@group
     187typedef struct @{
     188  rtems_unsigned32   offset;
     189  void              *buffer;
     190  rtems_unsigned32   length;
     191  rtems_unsigned32   status;
     192@}   Non_volatile_memory_Driver_arguments;
     193@end group
     194@end example
     195
     196The driver reads @code{length} bytes starting at @code{offset} into
     197the partition and places them at @code{buffer}.  The result is returned
     198in @code{status}.
     199
     200After the read operation is complete, the user supplied "disable reads handler"
     201is invoked to protect the memory area again.
     202
     203@section Write to a Particular Memory Partition
     204
     205This corresponds to the driver write call.   After validating the minor
     206number and arguments, this call enables writes to the specified
     207memory area by invoking the "enable writes handler", then unprotecting
     208the memory area, and finally actually writing to the indicated memory
     209area.  When invoked the @code{argument_block} is actually a pointer to
     210the following structure type:
     211
     212@example
     213@group
     214typedef struct @{
     215  rtems_unsigned32   offset;
     216  void              *buffer;
     217  rtems_unsigned32   length;
     218  rtems_unsigned32   status;
     219@}   Non_volatile_memory_Driver_arguments;
     220@end group
     221@end example
     222
     223The driver writes @code{length} bytes from @code{buffer} and
     224writes them to the non-volatile memory starting at @code{offset} into
     225the partition.  The result is returned in @code{status}.
     226
     227After the write operation is complete, the "disable writes handler"
     228is invoked to protect the memory area again.
     229
     230@section Erase the Non-Volatile Memory Area
     231
     232This is one of the IOCTL functions supported by the I/O control
     233device driver entry point.  When this IOCTL function is invoked,
     234the specified area of non-volatile memory is erased.
     235
  • doc/bsp_howto/rtc.t

    r06fee20 rbc950e87  
    99@chapter Real-Time Clock Driver
    1010
    11 XXX FILL ME IN
     11@section Introduction
    1212
     13The Real-Time Clock (@b{RTC}) driver is responsible for providing an
     14interface to an @b{RTC} device.  [NOTE: In this chapter, the abbreviation
     15@b{TOD} is used for @b{Time of Day}.]  The capabilities provided by this
     16driver are:
     17
     18@itemize @bullet
     19@item Set the RTC TOD to RTEMS TOD
     20@item Set the RTEMS TOD to the RTC TOD
     21@item Get the RTC TOD
     22@item Set the RTC TOD to the Specified TOD
     23@item Get the Difference Between the RTEMS and RTC TOD
     24@end itemize
     25
     26The reference implementation for a real-time clock driver can
     27be found in @code{c/src/lib/libbsp/shared/tod.c}.  This driver
     28is based on the libchip concept and can be easily configured
     29to work with any of the RTC chips supported by the RTC
     30chip drivers in the directory @code{c/src/lib/lib/libchip/rtc}.
     31There is a README file in this directory for each supported
     32RTC chip.  Each of these README explains how to configure the
     33shared libchip implementation of the RTC driver for that particular
     34RTC chip.
     35
     36The DY-4 DMV177 BSP uses the shared libchip implementation of the RTC
     37driver.  Its @code{RTC_Table} configuration table can be found in
     38@code{c/src/lib/libbsp/powerpc/dmv177/tod/config.c}.
     39
     40@section Initialization
     41
     42The @code{rtc_initialize} routine is responsible for initializing the
     43RTC chip so it can be used.  The shared libchip implementation of this
     44driver supports multiple RTCs and bases its initialization order on
     45the order the chips are defined in the @code{RTC_Table}.  Each chip
     46defined in the table may or may not be present on this particular board.
     47It is the responsibility of the @code{deviceProbe} to indicate the
     48presence of a particular RTC chip.  The first RTC found to be present
     49is considered the preferred RTC.
     50
     51In the shared libchip based implementation
     52of the driver, the following actions are performed:
     53
     54@example
     55@group
     56rtems_device_driver rtc_initialize(
     57  rtems_device_major_number  major,
     58  rtems_device_minor_number  minor_arg,
     59  void                      *arg
     60)
     61@{
     62   for each RTC configured in RTC_Table
     63     if the deviceProbe for this RTC indicates it is present
     64       set RTC_Minor to this device
     65       set RTC_Present to TRUE
     66       break out of this loop
     67
     68   if RTC_Present is not TRUE
     69     return RTEMS_INVALID_NUMBER to indicate that no RTC is present
     70
     71   register this minor number as the "/dev/rtc"
     72
     73   perform the deviceInitialize routine for the preferred RTC chip
     74
     75   for RTCs past this one in the RTC_Table
     76     if the deviceProbe for this RTC indicates it is present
     77       perform the deviceInitialize routine for this RTC chip
     78       register the configured name for this RTC
     79@}
     80@end group
     81@end example
     82
     83The @code{deviceProbe} routine returns TRUE if the device
     84configured by this entry in the @code{RTC_Table} is present. 
     85This configuration scheme allows one to support multiple versions
     86of the same board with a single BSP.  For example, if the first
     87generation of a board had Vendor A's RTC chip and the second
     88generation had Vendor B's RTC chip, RTC_Table could contain
     89information for both.  The @code{deviceProbe} configured
     90for Vendor A's RTC chip would need to return TRUE if the
     91board was a first generation one.  The @code{deviceProbe}
     92routines are very board dependent.
     93
     94@section setRealTimeToRTEMS
     95
     96The @code{setRealTimeToRTEMS} routine sets the current RTEMS TOD to that
     97of the preferred RTC. 
     98
     99@example
     100@group
     101void setRealTimeToRTEMS(void)
     102@{
     103  if no RTCs are present
     104    return
     105
     106  invoke the deviceGetTime routine for the preferred RTC
     107  set the RTEMS TOD using rtems_clock_set
     108@}
     109@end group
     110@end example
     111
     112@section setRealTimeFromRTEMS
     113
     114The @code{setRealTimeFromRTEMS} routine sets the preferred RTC TOD to the
     115current RTEMS TOD.
     116
     117@example
     118@group
     119void setRealTimeFromRTEMS(void)
     120@{
     121  if no RTCs are present
     122    return
     123
     124  obtain the RTEMS TOD using rtems_clock_get
     125  invoke the deviceSetTime routine for the preferred RTC
     126@}
     127@end group
     128@end example
     129
     130@section getRealTime
     131
     132The @code{getRealTime} returns the preferred RTC TOD to the
     133caller.
     134
     135@example
     136@group
     137void getRealTime( rtems_time_of_day *tod )
     138@{
     139  if no RTCs are present
     140    return
     141
     142  invoke the deviceGetTime routine for the preferred RTC
     143@}
     144@end group
     145@end example
     146
     147@section setRealTime
     148
     149The @code{setRealTime} routine sets the preferred RTC TOD to the
     150TOD specified by the caller.
     151
     152@example
     153@group
     154void setRealTime( rtems_time_of_day *tod )
     155@{
     156  if no RTCs are present
     157    return
     158
     159  invoke the deviceSetTime routine for the preferred RTC
     160@}
     161@end group
     162@end example
     163
     164@section checkRealTime
     165
     166The @code{checkRealTime} routine returns the number of seconds
     167difference between the RTC TOD and the current RTEMS TOD.
     168
     169@example
     170@group
     171int checkRealTime( void )
     172@{
     173  if no RTCs are present
     174    return -1
     175
     176 
     177  obtain the RTEMS TOD using rtems_clock_get
     178  get the TOD from the preferred RTC using the deviceGetTime routine
     179
     180  convert the RTEMS TOD to seconds
     181  convert the RTC TOD to seconds
     182 
     183  return the RTEMS TOD in seconds - RTC TOD in seconds
     184@}
     185@end group
     186@end example
     187
  • doc/bsp_howto/shmsupp.t

    r06fee20 rbc950e87  
    99@chapter Shared Memory Support Driver
    1010
    11 XXX FILL ME IN
    12 
     11The Shared Memory Support Driver is responsible for providing glue
     12routines and configuration information required by the Shared
     13Memory Multiprocessor Communications Interface (MPCI).  The
     14Shared Memory Support Driver tailors the portable Shared
     15Memory Driver to a particular target platform.
     16
     17This driver is only required in shared memory multiprocessing
     18systems that use the RTEMS mulitprocessing support.  For more
     19information on RTEMS multiprocessing capabilities and the
     20MPCI, refer to the @b{Multiprocessing Manager} chapter
     21of the @b{RTEMS Application C User's Guide}.
     22
     23@section Shared Memory Configuration Table
     24
     25The Shared Memory Configuration Table is defined in the following
     26structure:
     27
     28@example
     29@group
     30typedef volatile rtems_unsigned32 vol_u32;
     31
     32typedef struct @{
     33  vol_u32 *address;        /* write here for interrupt    */
     34  vol_u32  value;          /* this value causes interrupt */
     35  vol_u32  length;         /* for this length (0,1,2,4)   */
     36@} Shm_Interrupt_information;
     37
     38struct shm_config_info @{
     39  vol_u32           *base;       /* base address of SHM         */
     40  vol_u32            length;     /* length (in bytes) of SHM    */
     41  vol_u32            format;     /* SHM is big or little endian */
     42  vol_u32          (*convert)(); /* neutral conversion routine */
     43  vol_u32            poll_intr; /* POLLED or INTR driven mode  */
     44  void             (*cause_intr)( rtems_unsigned32 );
     45  Shm_Interrupt_information   Intr;     /* cause intr information      */
     46@};
     47
     48typedef struct shm_config_info shm_config_table;
     49@end group
     50@end example
     51
     52where the fields are defined as follows:
     53
     54@table @b
     55@item base
     56is the base address of the shared memory buffer used to pass
     57messages between the nodes in the system.
     58
     59@item length
     60is the length (in bytes) of the shared memory buffer used to pass
     61messages between the nodes in the system.
     62
     63@item format
     64is either SHM_BIG or SHM_LITTLE to indicate that the neutral format
     65of the shared memory area is big or little endian.  The format
     66of the memory should be chosen to match most of the inter-node traffic.
     67
     68@item convert
     69is the address of a routine which converts from native format to
     70neutral format.   Ideally, the neutral format is the same as the
     71native format so this routine is quite simple.
     72
     73@item poll_intr
     74is either INTR_MODE or POLLED_MODE to indicate how the node will be
     75informed of incoming messages.
     76
     77@item cause_intr
     78
     79@item Intr
     80is the information required to cause an interrupt on a node.  This
     81structure contains the following fields:
     82@table @b
     83@item address
     84is the address to write at to cause an interrupt on that node.
     85For a polled node, this should be NULL.
     86
     87@item value
     88is the value to write to cause an interrupt.
     89
     90@item length
     91is the length of the entity to write on the node to cause an interrupt.
     92This can be 0 to indicate polled operation, 1 to write a byte, 2 to
     93write a sixteen-bit entity, and 4 to write a thirty-two bit entity.
     94@end table
     95@end table
     96
     97@section Primitives
     98
     99@subsection Convert Address
     100
     101The @code{Shm_Convert_address} is responsible for converting an address
     102of an entity in the shared memory area into the address that should be
     103used from this node.  Most targets will simply return the address
     104passed to this routine.  However, some target boards will have a special
     105window onto the shared memory.  For example, some VMEbus boards have
     106special address windows to access addresses that are normally reserved
     107in the CPU's address space.
     108
     109@example
     110@group
     111void *Shm_Convert_address( void *address )
     112@{
     113   return the local address version of this bus address
     114@}
     115@end group
     116@end example
     117
     118@subsection Get Configuration
     119
     120The @code{Shm_Get_configuration} routine is responsible for filling in the
     121Shared Memory Configuration Table passed to it. 
     122
     123@example
     124@group
     125void Shm_Get_configuration(
     126  rtems_unsigned32   localnode,
     127  shm_config_table **shmcfg
     128)
     129@{
     130   fill in the Shared Memory Configuration Table
     131@}
     132@end group
     133@end example
     134
     135@subsection Locking Primitives
     136
     137This is a collection of routines that are invoked by the portable
     138part of the Shared Memory Driver to manage locks in the shared
     139memory buffer area.  Accesses to the shared memory must be
     140atomic.  Two nodes in a multiprocessor system must not be manipulating
     141the shared data structures simultaneously.  The locking primitives
     142are used to insure this. 
     143
     144To avoid deadlock, local processor interrupts should be disabled the entire
     145time the locked queue is locked.
     146
     147The locking primitives operate on the lock
     148@code{field} of the @code{Shm_Locked_queue_Control}
     149data structure.  This structure is defined as follows:
     150
     151@example
     152@group
     153typedef struct @{
     154  vol_u32 lock;  /* lock field for this queue    */
     155  vol_u32 front; /* first envelope on queue      */
     156  vol_u32 rear;  /* last envelope on queue       */
     157  vol_u32 owner; /* receiving (i.e. owning) node */
     158@} Shm_Locked_queue_Control;
     159@end group
     160@end example
     161
     162where each field is defined as follows:
     163
     164@table @b
     165@item lock
     166is the lock field.  Every node in the system must agree on how this
     167field will be used.  Many processor families provide an atomic
     168"test and set" instruction that is used to manage this field.
     169
     170@item front
     171is the index of the first message on this locked queue.
     172
     173@item rear
     174is the index of the last message on this locked queue.
     175
     176@item owner
     177is the node number of the node that currently has this structure locked.
     178
     179@end table
     180
     181@subsubsection Initializing a Shared Lock
     182
     183The @code{Shm_Initialize_lock} routine is responsible for
     184initializing the lock field.  This routines usually is implemented
     185as follows:
     186
     187@example
     188@group
     189void Shm_Initialize_lock(
     190  Shm_Locked_queue_Control *lq_cb
     191)
     192@{
     193  lq_cb->lock = LQ_UNLOCKED;
     194@}
     195@end group
     196@end example
     197
     198@subsubsection Acquiring a Shared Lock
     199
     200The @code{Shm_Lock} routine is responsible for
     201acquiring the lock field.  Interrupts should be
     202disabled while that lock is acquired.  If the lock
     203is currently unavailble, then the locking routine
     204should delay a few microseconds to allow the other
     205node to release the lock.  Doing this reduces bus contention
     206for the lock.  This routines usually is implemented as follows:
     207
     208@example
     209@group
     210void Shm_Lock(
     211  Shm_Locked_queue_Control *lq_cb
     212)
     213@{
     214  disable processor interrupts
     215    set Shm_isrstat to previous interrupt disable level
     216   
     217    while ( TRUE ) @{
     218      atomically attempt to acquire the lock
     219      if the lock was acquired
     220        return
     221      delay some small period of time
     222    @}
     223@}
     224@end group
     225@end example
     226
     227@subsubsection Releasing a Shared Lock
     228
     229The @code{Shm_Unlock} routine is responsible for
     230releasing the lock field and reenabling processor
     231interrupts.  This routines usually is implemented as follows:
     232
     233@example
     234@group
     235void Shm_Unlock(
     236  Shm_Locked_queue_Control *lq_cb
     237)
     238@{
     239  set the lock to the unlocked value
     240  reenable processor interrupts to their level prior
     241    to the lock being acquired.  This value was saved
     242    in the global variable Shm_isrstat
     243@}
     244@end group
     245@end example
     246
     247@section Installing the MPCI ISR
     248
     249The @code{Shm_setvec} is invoked by the portable portion
     250of the shared memory to install the interrupt service routine
     251that is invoked when an incoming message is announced.  Some
     252target boards support an interprocessor interrupt or mailbox
     253scheme and this is where the ISR for that interrupt would be
     254installed.
     255
     256On an interrupt driven node, this routine would be implemented
     257as follows:
     258
     259@example
     260@group
     261void Shm_setvec( void )
     262@{
     263  install the interprocessor communications ISR
     264@}
     265@end group
     266@end example
     267
     268On a polled node, this routine would be empty.
     269
  • doc/bsp_howto/support.t

    r06fee20 rbc950e87  
    77@c
    88
    9 @chapter Required Support Routines
    10 
    11 XXX FILL ME IN
    12 
     9@chapter Miscellaneous Support Files
     10
     11@section GCC Compiler Specifications File
     12
     13The file @code{bsp_specs} defines the start files and libraries
     14that are always used with this BSP.  The format of this file
     15is admittedly cryptic and this document will make no attempt
     16to explain it completely.  Below is the @code{bsp_specs}
     17file from the PowerPC psim BSP:
     18
     19@example
     20@group
     21%rename cpp old_cpp
     22%rename lib old_lib
     23%rename endfile old_endfile
     24%rename startfile old_startfile
     25%rename link old_link
     26
     27*cpp:
     28%(old_cpp) %@{qrtems: -D__embedded__@} -Asystem(embedded)
     29
     30*lib:
     31%@{!qrtems: %(old_lib)@} %@{qrtems: --start-group \
     32%@{!qrtems_debug: -lrtemsall@} %@{qrtems_debug: -lrtemsall_g@} \
     33-lc -lgcc --end-group  ecrtn%O%s \
     34%@{!qnolinkcmds: -T linkcmds%s@}@}
     35
     36*startfile:
     37%@{!qrtems: %(old_startfile)@} %@{qrtems:  ecrti%O%s \
     38%@{!qrtems_debug: startsim.o%s@} \
     39%@{qrtems_debug: startsim_g.o%s@}@}
     40
     41*link:
     42%@{!qrtems: %(old_link)@} %@{qrtems: -Qy -dp -Bstatic \
     43-T linkcmds%s -e _start -u __vectors@}
     44@end group
     45@end example
     46
     47The first section of this file renames the built-in definition of
     48some specification variables so they can be augmented without
     49embedded their original definition.  The subsequent sections
     50specify what behavior is expected when the @code{-qrtems} or
     51@code{-qrtems_debug} option is specified. 
     52
     53The @code{*cpp} definition specifies that when @code{-qrtems}
     54is specified, predefine the preprocessor symbol @code{__embedded__}.
     55
     56The @code{*lib} section insures that the RTEMS library, BSP specific
     57linker script, gcc support library, and the EABI specific @code{ecrtn}
     58file are used.
     59
     60The @code{*startfile} section specifies that the BSP specific file
     61@code{startsim.o} will be used instead of @code{crt0.o}.  In addition,
     62the EABI specific file @code{ecrti.o} will be linked in with the
     63executable.
     64
     65The @code{*link} section specifies the arguments that will be passed to
     66the linker.
     67
     68The format of this file is specific to the GNU Compiler Suite.  The
     69argument used to override and extend the compiler built-in specifications
     70is relatively new to the toolset.  The @code{-specs} option is present
     71in all @code{egcs} distributions and @code{gcc} distributions starting
     72with version 2.8.0.
     73
     74@section README Files
     75
     76Most BSPs provide one or more @code{README} files.  Generally, there
     77is a @code{README} file at the top of the BSP source.  This file
     78describes the board and its hardware configuration, provides vendor
     79information, local configuration information, information on downloading
     80code to the board, debugging, etc..  The intent of this
     81file is to help someone begin to use the BSP faster. 
     82
     83A @code{README} file in a BSP subdirectory typically explains something
     84about the contents of that subdirectory in greater detail.  For example,
     85it may list the documentation available for a particular peripheral
     86controller and how to obtain that documentation.  It may also explain some
     87particularly cryptic part of the software in that directory or provide
     88rationale on the implementation.
     89
     90@section times
     91
     92This file contains the results of the RTEMS Timing Test Suite.  It is
     93in a standard format so that results from one BSP can be easily compared
     94with those of another target board.
     95
     96If a BSP supports multiple variants, then there may be multiple @code{times}
     97files.  Usually these are named @code{times.VARIANTn}.
     98
     99@section Tools Subdirectory
     100
     101Some BSPs provide additional tools that aid in using the target board.
     102These tools run on the development host and are built as part of building
     103the BSP.  Most common is a script to automate running the RTEMS Test Suites
     104on the BSP.  Examples of this include:
     105
     106@itemize @bullet
     107
     108@item @code{powerpc/psim} includes scripts to ease use of the simulator
     109
     110@item @code{m68k/mvme162} includes a utility to download across the
     111VMEbus into target memory if the host is a VMEbus board in the same
     112chasis.
     113
     114@item @code{unix/posix} includes scripts to run the tests automatically
     115on this BSP.
     116
     117@end itemize
     118
     119@section bsp.h Include File
     120
     121The file @code{include/bsp.h} contains prototypes and definitions
     122specific to this board.  Every BSP is required to provide a @code{bsp.h}.
     123The best approach to writing a @code{bsp.h} is copying an existing one
     124as a starting point. 
     125
     126Many @code{bsp.h} files provide prototypes of variables defined
     127in the linker script (@code{linkcmds}).
     128
     129There are a number of fields in this file that are used only by the
     130RTEMS Test Suites.  The following is a list of these:
     131
     132@itemize @bullet
     133@item @code{MAX_LONG_TEST_DURATION} - the longest length of time a
     134"long running" test should run.
     135
     136@item @code{MAX_SHORT_TEST_DURATION} - the longest length of time a
     137"short running" test should run.
     138
     139@item @code{MUST_WAIT_FOR_INTERRUPT} - modifies behavior of @code{tm27}.
     140
     141@item @code{Install_tm27_vector} - installs the interrupt service
     142routine for the Interrupt Benchmark Test (@code{tm27}).
     143
     144@item @code{Cause_tm27_intr} - generates the interrupt source
     145used in the Interrupt Benchmark Test (@code{tm27}).
     146
     147@item @code{Clear_tm27_intr} - clears the interrupt source
     148used in the Interrupt Benchmark Test (@code{tm27}).
     149
     150@item @code{Lower_tm27_intr} - lowers the interrupt mask so the
     151interrupt source used in the Interrupt Benchmark Test (@code{tm27})
     152can generate a nested interrupt.
     153
     154@end itemize
     155
     156@section Calling Overhead File
     157
     158The file @code{include/coverhd.h} contains the overhead associated
     159with invoking each directive.  This overhead consists of the execution
     160time required to package the parameters as well as to execute the "jump to
     161subroutine" and "return from subroutine" sequence.  The intent of this
     162file is to help separate the calling overhead from the actual execution
     163time of a directive.  This file is only used by the tests in the
     164RTEMS Timing Test Suite.
     165
     166The numbers in this file are obtained by running the "Timer Overhead"
     167@code{tmoverhd} test.  The numbers in this file may be 0 and no
     168overhead is subtracted from the directive execution times reported by
     169the Timing Suite.
     170
     171@section sbrk() Implementation
     172
     173If the BSP wants to dynamically extend the heap used by the
     174C Library memory allocation routines (i.e. @code{malloc} family),
     175then this routine must be functional.  The following is the
     176prototype for this routine:
     177
     178@example
     179void * sbrk(size_t increment)
     180@end example
     181
     182The @code{increment} amount is based upon the @code{sbrk_amount}
     183parameter passed to the @code{RTEMS_Malloc_Initialize} during system
     184initialization.
     185See @ref{Initialization Code RTEMS Pretasking Callback} for more
     186information.
     187
     188There is a default implementation which returns an error to indicate
     189that the heap can not be extended.  This implementation can be
     190found in @code{c/src/lib/libbsp/shared/sbrk.c}.  Many of the BSPs
     191use this shared implementation.  In order to use this implementation,
     192the file @code{Makefile.in} in the BSP's @code{startup} directory
     193must be modified so that the @code{$VPATH} variable searches
     194both the @code{startup} directory and the shared directory.  The following
     195illustates the @code{VPATH} setting in the PowerPC psim BSP's
     196@code{startup/Makefile.in}:
     197
     198@example
     199VPATH = @@srcdir@@:@@srcdir@@/../../../shared
     200@end example
     201
     202This instructs make to look in all of the directories in the @code{VPATH}
     203for the source files.  The directories will be examined in the order
     204they are specified.
     205
     206@section bsp_cleanup() - Cleanup the Hardware
     207
     208The @code{bsp_cleanup()} is the last C code invoked.  Most of the BSPs
     209use the same shared version of @code{bsp_cleanup()} that does nothing.
     210This implementation is located in the following file:
     211
     212@example
     213c/src/lib/libbsp/shared/bspclean.c
     214@end example
     215
     216The @code{bsp_cleanup()} routine can be used to return to a ROM monitor,
     217insure that interrupt sources are disabled, etc..  This routine is the
     218last place to insure a clean shutdown of the hardware.
     219
     220@section set_vector() - Install an Interrupt Vector
     221
     222The @code{set_vector} routine is responsible for installing an interrupt
     223vector.  It invokes the support routines necessary to install an
     224interrupt handler as either a "raw" or an RTEMS interrupt handler.  Raw
     225handlers bypass the RTEMS interrupt structure and are responsible for
     226saving and restoring all their own registers.  Raw handlers are useful
     227for handling traps, debug vectors, etc..
     228
     229The @code{set_vector} routine is a central place to perform
     230interrupt controller manipulation and encapsulate that information. 
     231It is usually implemented as follows:
     232
     233@example
     234@group
     235rtems_isr_entry set_vector(                     /* returns old vector */
     236  rtems_isr_entry     handler,                  /* isr routine        */
     237  rtems_vector_number vector,                   /* vector number      */
     238  int                 type                      /* RTEMS or RAW intr  */
     239)
     240@{
     241  if the type is RAW
     242    install the raw vector
     243  else
     244    use rtems_interrupt_catch to install the vector
     245
     246  perform any interrupt controller necessary to unmask
     247    the interrupt source
     248
     249  return the previous handler
     250@}
     251@end group
     252@end example
     253
     254
     255@b{NOTE:}  @code{set_vector} is provided by the majority of BSPs but
     256not all.  In particular, the i386 BSPs use a different scheme. 
     257
  • doc/bsp_howto/timer.t

    r06fee20 rbc950e87  
    99@chapter Timer Driver
    1010
    11 You can program the timer driver for your own needs, but here are two uses
    12 of it:
     11The timer driver is primarily used by the RTEMS Timing Tests. 
     12This driver provides as accurate a benchmark timer as possible.
     13It typically reports its time in microseconds, CPU cycles, or
     14bus cycles.  This information can be very useful for determining
     15precisely what pieces of code require optimization and to measure the
     16impact of specific minor changes.
    1317
    14 @section UART'S FIFO Full Mode
     18The gen68340 BSP also uses the TImer Driver to support a high performance
     19mode of the on-CPU UART.
     20
     21@section Benchmark Timer
     22
     23The RTEMS Timing Test Suite requires a benchmark timer.  The
     24RTEMS Timing Test Suite is very helpful for determining
     25the performance of target hardware and comparing its performance
     26to that of other RTEMS targets.
     27
     28This section describes the routines which are assumed to exist by
     29the RTEMS Timing Test Suite.  The names used are @b{EXACTLY} what
     30is used in the RTEMS Timing Test Suite so follow the naming convention.
     31
     32@subsection Timer_initialize
     33
     34Initialize the timer source.
     35
     36@example
     37void Timer_initialize(void)
     38@{
     39  initialize the benchmark timer
     40@}
     41@end example
     42
     43@subsection Read_timer
     44
     45The @code{Read_timer} routine
     46returns the number of benchmark time units (typically microseconds)
     47that have elapsed since the last call to @code{Timer_initialize}.
     48
     49@example
     50int Read_timer(void)
     51@{
     52  stop time = read the hardware timer
     53  if the subtract overhead feature is enabled
     54    subtract overhead from stop time
     55  return the stop time
     56@}
     57@end example
     58
     59Many implementations of this routine subtract the overhead required
     60to initialize and read the benchmark timer.  This makes the times reported
     61more accurate.
     62
     63Some implementations report 0 if the harware timer value change is
     64sufficiently small.  This is intended to indicate that the execution time
     65is below the resolution of the timer.
     66
     67@subsection An Empty Function
     68
     69This routine is invoked by the RTEMS Timing Test Suite to measure
     70the cost of invoking a subroutine.
     71
     72@example
     73rtems_status_code Empty_function (void)
     74@{
     75  return RTEMS_SUCCESSFUL;
     76@}
     77@end example
     78
     79@subsection Set_find_average_overhead
     80
     81This routine is invoked by the "Check Timer" (@code{tmck}) test in the
     82RTEMS Timing Test Suite.  It makes the @code{Read_timer}
     83routine NOT subtract the overhead required
     84to initialize and read the benchmark timer.  This is used
     85by the @code{tmoverhd} test to determine the overhead
     86required to initialize and read the timer.
     87
     88@example
     89void Set_find_average_overhead(rtems_boolean find_flag)
     90@{
     91    disable the subtract overhead feature
     92@}
     93@end example
     94
     95The @code{Timer_driver_Find_average_overhead} variable is usually
     96used to indicate the state of the "subtract overhead feature".
     97
     98@section gen68340 UART FIFO Full Mode
    1599
    16100The gen68340 BSP is an example of the use of the timer to support the UART
    17101input FIFO full mode (FIFO means First In First Out and roughly means
    18102buffer). This mode consists in the UART raising an interrupt when n
    19 characters have been received (n is the UA RT's FIFO length). It results
     103characters have been received (@i{n} is the UART's FIFO length). It results
    20104in a lower interrupt processing time, but the problem is that a scanf
    21 primitive will block on a receipt of less than n characters. The solution
     105primitive will block on a receipt of less than @i{n} characters. The solution
    22106is to set a timer that will check whether there are some characters
    23 waiting in th e UART's input FIFO. The delay time has to be set carefully
     107waiting in the UART's input FIFO. The delay time has to be set carefully
    24108otherwise high rates will be broken:
    25109
     
    29113entered, set a long delay,
    30114
    31 @item otherwise set the delay to the delay needed for n characters
     115@item otherwise set the delay to the delay needed for @i{n} characters
    32116receipt.
    33117
    34118@end itemize
    35119
    36 @section Measuring RTEMS Primitives Time
    37 
    38 RTEMS Timing Test Suite needs a timer support. You have to provide two
    39 primitives:
    40120
    41121
    42 
    43 Function
    44 
    45 Description
    46 
    47 @example
    48 void Timer_initialize (void)
    49 @end example
    50 
    51 Initialize the timer to be a counter to the microsecond.
    52 
    53 @example
    54 int Read_timer (void)
    55 @end example
    56 
    57 Returns the number of microseconds elapsed since the last call to
    58 Timer_initialize.
    59 
    60 @example
    61 rtems_status_code Empty_function (void)
    62 
    63 return RTEMS_SUCCESSFUL;
    64 @end example
    65 
    66 @example
    67 void Set_find_average_overhead (rtems_boolean find_flag)
    68 @end example
    69 
    70 DOES NOTHING ??????????
    71 
    72                
    73 
    74 
  • doc/networking/driver.t

    r06fee20 rbc950e87  
    99@c
    1010
    11 @chapter Writing RTEMS Network Device Drivers
     11@chapter Networking Driver
    1212
    1313@section Introduction
  • doc/new_chapters/Makefile

    r06fee20 rbc950e87  
    2424   io.texi key.texi memorymgmt.texi message.texi mutex.texi procenv.texi \
    2525   process.texi sched.texi semaphores.texi signal.texi systemdb.texi \
    26    thread.texi
     26   thread.texi \
     27   stackchk.texi rtmonuse.texi cpuuse.texi error.texi monitor.texi
    2728
    2829FILES= posix_users.texi preface.texi \
     
    5455        $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \
    5556            posix_users.texi
    56 
    5757
    5858clean:
     
    171171            -n "" ${*}.t
    172172
     173stackchk.texi: stackchk.t Makefile
     174        $(BMENU) -p "" \
     175            -u "Top" \
     176            -n "" ${*}.t
     177
     178rtmonuse.texi: rtmonuse.t Makefile
     179        $(BMENU) -p "" \
     180            -u "Top" \
     181            -n "" ${*}.t
     182
     183cpuuse.texi: cpuuse.t Makefile
     184        $(BMENU) -p "" \
     185            -u "Top" \
     186            -n "" ${*}.t
     187
     188error.texi: error.t Makefile
     189        $(BMENU) -p "" \
     190            -u "Top" \
     191            -n "" ${*}.t
     192
     193monitor.texi: monitor.t Makefile
     194        $(BMENU) -p "" \
     195            -u "Top" \
     196            -n "" ${*}.t
  • doc/new_chapters/files.t

    r06fee20 rbc950e87  
    2929@item @code{umask} - Sets a file creation mask
    3030@item @code{link} - Creates a link to a file
     31@item @code{symlink} - Creates a symbolic link to a file
     32@item @code{readlink} - Obtain the name of the link destination
    3133@item @code{mkdir} - Makes a directory
    3234@item @code{mkfifo} - Makes a FIFO special file
     
    742744
    743745@page
     746@subsection symlink - Creates a symbolic link to a file
     747
     748@subheading CALLING SEQUENCE:
     749
     750@ifset is-C
     751@example
     752#include <unistd.h>
     753
     754int symlink(
     755  const char *topath,
     756  const char *frompath
     757);
     758@end example
     759@end ifset
     760
     761@ifset is-Ada
     762@end ifset
     763
     764@subheading STATUS CODES:
     765
     766@table @b
     767
     768@item EACCES
     769Search permission is denied for a directory in a file's path prefix
     770
     771@item EEXIST
     772The named file already exists.
     773
     774@item ENAMETOOLONG
     775Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
     776effect.
     777
     778@item ENOENT
     779A file or directory does not exist.
     780
     781@item ENOSPC
     782No space left on disk.
     783
     784@item ENOTDIR
     785A component of the specified pathname was not a directory when a directory
     786was expected.
     787
     788@item EPERM
     789Operation is not permitted.  Process does not have the appropriate priviledges
     790or permissions to perform the requested operations.
     791
     792@item EROFS
     793Read-only file system.
     794
     795@end table
     796
     797@subheading DESCRIPTION:
     798
     799The @code{symlink()} function creates a symbolic link from the frombath to the
     800topath.  The symbolic link will be interpreted at run-time.
     801
     802If the @code{symlink()} function fails, no directories are modified.
     803
     804The caller may (or may not) need permission to access the existing file.
     805
     806@subheading NOTES:
     807
     808NONE
     809
     810@page
     811@subsection readlink - Obtain the name of a symbolic link destination
     812
     813@subheading CALLING SEQUENCE:
     814
     815@ifset is-C
     816@example
     817#include <unistd.h>
     818
     819int readlink(
     820  const char *path,
     821  char       *buf,
     822  size_t      bufsize
     823);
     824
     825@end example
     826@end ifset
     827
     828@ifset is-Ada
     829@end ifset
     830
     831@subheading STATUS CODES:
     832
     833@table @b
     834
     835@item EACCES
     836Search permission is denied for a directory in a file's path prefix
     837
     838@item ENAMETOOLONG
     839Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
     840effect.
     841
     842@item ENOENT
     843A file or directory does not exist.
     844
     845@item ENOTDIR
     846A component of the prefix pathname was not a directory when a directory
     847was expected.
     848
     849@item ELOOP
     850Too many symbolic links were encountered in the pathname.
     851
     852@item EINVAL
     853The pathname does not refer to a symbolic link
     854
     855@item EFAULT
     856An invalid pointer was passed into the @code{readlink()} routine.
     857
     858@end table
     859
     860@subheading DESCRIPTION:
     861
     862The @code{readlink()} function places the symbolic link destination into
     863@code{buf} argument and returns the number of characters copied.
     864
     865If the symbolic link destination is longer than bufsize characters the
     866name will be truncated.
     867
     868@subheading NOTES:
     869
     870NONE
     871
     872@page
    744873@subsection mkdir - Makes a directory
    745874
  • doc/new_chapters/gen_section

    r06fee20 rbc950e87  
    130130       strpbrk strrchr strspn strstr strtok stlen"
    131131    ;;
     132  misc_stackchk)
     133    CHAPTER_CAPS="Stack Bounds Checker"
     134    CHAPTER_LOWER="stack bounds checker"
     135    ROUTINES="Stack_check_Initialize Stack_check_Dump_usage"
     136    ;;
     137  misc_rtmonuse)
     138    CHAPTER_CAPS="Rate Monotonic Period Statistics"
     139    CHAPTER_LOWER="rate monotonic period statistics"
     140    ROUTINES="Period_usage_Initialize Period_usage_Reset \
     141        Period_usage_Update Period_usage_Dump"
     142    ;;
     143  misc_cpuuse)
     144    CHAPTER_CAPS="CPU Usage Statistics"
     145    CHAPTER_LOWER="CPU usage statistics"
     146    ROUTINES="CPU_usage_Dump CPU_usage_Reset"
     147    ;;
     148  misc_error)
     149    CHAPTER_CAPS="Error Reporting Support"
     150    CHAPTER_LOWER="error reporting support"
     151    ROUTINES="rtems_error rtems_panic"
     152    ;;
     153  misc_monitor)
     154    CHAPTER_CAPS="Monitor Task"
     155    CHAPTER_LOWER="monitor task"
     156    ROUTINES="rtems_monitor_init rtems_monitor_wakeup"
     157    ;;
    132158  *)
    133159    echo "Unknown chapter name"
  • doc/new_chapters/posix_users.texi

    r06fee20 rbc950e87  
    108108@include confspace.texi
    109109@include adminiface.texi
     110@include stackchk.texi
     111@include rtmonuse.texi
     112@include cpuuse.texi
     113@include error.texi
     114@include monitor.texi
    110115@ifinfo
    111116@node Top, Preface, (dir), (dir)
     
    138143* Configuration Space Manager::
    139144* Administration Interface Manager::
     145* Stack Bounds Checker::
     146* Rate Monotonic Period Statistics::
     147* CPU Usage Statistics::
     148* Error Reporting Support::
     149* Monitor Task::
    140150* Command and Variable Index::
    141151* Concept Index::
  • doc/new_chapters/signal.t

    r06fee20 rbc950e87  
    109109@subheading NOTES:
    110110
     111NONE
     112
    111113@page
    112114@subsection sigdelset - Delete a Signal from a Signal Set
  • doc/posix1003.1/Makefile

    r06fee20 rbc950e87  
    4646$(PROJECT).dvi: $(FILES)
    4747        $(TEXI2DVI) -v $(PROJECT).texi
    48         texi2dvi $(PROJECT).texi
     48        texi2dvi -v $(PROJECT).texi
    4949
    5050ch01.texi: ch01.t
  • doc/posix1003.1/ch06.t

    r06fee20 rbc950e87  
    2323@example
    2424dup(), Function, Implemented
    25 dup2(), Function, Untested Implementation
     25dup2(), Function, Untested Iimplementation
    2626@end example
    2727
  • doc/posix1003.1/ch14.t

    r06fee20 rbc950e87  
    4747
    4848@example
    49 timer_create(), Function, Implemented
     49timer_create(), Function, Dummy Implementation
    5050@end example
    5151
     
    5353
    5454@example
    55 timer_delete(), Function, Implemented
     55timer_delete(), Function, Dummy Implementation
    5656@end example
    5757
     
    5959
    6060@example
    61 timer_settime(), Function, Implemented
    62 timer_gettime(), Function, Implemented
    63 timer_getoverrun(), Function, Implemented
     61timer_settime(), Function, Dummy Implementation
     62timer_gettime(), Function, Dummy Implementation
     63timer_getoverrun(), Function, Dummy Implementation
    6464@end example
    6565
  • doc/started/Makefile

    r06fee20 rbc950e87  
    4242# run texi2dvi twice to generate the xref's properly.
    4343$(PROJECT).dvi: $(FILES)
    44         $(TEXI2DVI) $(PROJECT).texi
    45         texi2dvi $(PROJECT).texi
     44        $(TEXI2DVI) -v $(PROJECT).texi
     45        texi2dvi -v $(PROJECT).texi
    4646
    4747intro.texi: intro.t versions.texi
  • doc/supplements/hppa1_1/cputable.t

    r06fee20 rbc950e87  
    4848@table @code
    4949@item pretasking_hook
    50 is the address of the
    51 user provided routine which is invoked once RTEMS initialization
    52 is complete but before interrupts and tasking are enabled.  This
    53 field may be NULL to indicate that the hook is not utilized.
     50is the address of the user provided routine which is invoked
     51once RTEMS APIs are initialized.  This routine will be invoked
     52before any system tasks are created.  Interrupts are disabled.
     53This field may be NULL to indicate that the hook is not utilized.
    5454
    5555@item predriver_hook
    5656is the address of the user provided
    57 routine which is invoked with tasking enabled immediately before
    58 the MPCI and device drivers are initialized. RTEMS
    59 initialization is complete, interrupts and tasking are enabled,
    60 but no device drivers are initialized.  This field may be NULL to
    61 indicate that the hook is not utilized.
     57routine that is invoked immediately before the
     58the device drivers and MPCI are initialized. RTEMS
     59initialization is complete but interrupts and tasking are disabled.
     60This field may be NULL to indicate that the hook is not utilized.
    6261
    6362@item postdriver_hook
    6463is the address of the user provided
    65 routine which is invoked with tasking enabled immediately after
    66 the MPCI and device drivers are initialized. RTEMS
    67 initialization is complete, interrupts and tasking are enabled,
    68 and the device drivers are initialized.  This field may be NULL
    69 to indicate that the hook is not utilized.
     64routine that is invoked immediately after the
     65the device drivers and MPCI are initialized. RTEMS
     66initialization is complete but interrupts and tasking are disabled.
     67This field may be NULL to indicate that the hook is not utilized.
    7068
    7169@item idle_task
  • doc/supplements/i386/cputable.t

    r06fee20 rbc950e87  
    4747@table @code
    4848@item pretasking_hook
    49 is the address of the
    50 user provided routine which is invoked once RTEMS initialization
    51 is complete but before interrupts and tasking are enabled.  This
    52 field may be NULL to indicate that the hook is not utilized.
     49is the address of the user provided routine which is invoked
     50once RTEMS APIs are initialized.  This routine will be invoked
     51before any system tasks are created.  Interrupts are disabled.
     52This field may be NULL to indicate that the hook is not utilized.
    5353
    5454@item predriver_hook
    5555is the address of the user provided
    56 routine which is invoked with tasking enabled immediately before
    57 the MPCI and device drivers are initialized. RTEMS
    58 initialization is complete, interrupts and tasking are enabled,
    59 but no device drivers are initialized.  This field may be NULL to
    60 indicate that the hook is not utilized.
     56routine that is invoked immediately before the
     57the device drivers and MPCI are initialized. RTEMS
     58initialization is complete but interrupts and tasking are disabled.
     59This field may be NULL to indicate that the hook is not utilized.
    6160
    6261@item postdriver_hook
    6362is the address of the user provided
    64 routine which is invoked with tasking enabled immediately after
    65 the MPCI and device drivers are initialized. RTEMS
    66 initialization is complete, interrupts and tasking are enabled,
    67 and the device drivers are initialized.  This field may be NULL
    68 to indicate that the hook is not utilized.
     63routine that is invoked immediately after the
     64the device drivers and MPCI are initialized. RTEMS
     65initialization is complete but interrupts and tasking are disabled.
     66This field may be NULL to indicate that the hook is not utilized.
    6967
    7068@item idle_task
  • doc/supplements/i960/cputable.t

    r06fee20 rbc950e87  
    5555@table @code
    5656@item pretasking_hook
    57 is the address of the
    58 user provided routine which is invoked once RTEMS initialization
    59 is complete but before interrupts and tasking are enabled.  This
    60 field may be NULL to indicate that the hook is not utilized.
     57is the address of the user provided routine which is invoked
     58once RTEMS APIs are initialized.  This routine will be invoked
     59before any system tasks are created.  Interrupts are disabled.
     60This field may be NULL to indicate that the hook is not utilized.
    6161
    6262@item predriver_hook
    6363is the address of the user provided
    64 routine which is invoked with tasking enabled immediately before
    65 the MPCI and device drivers are initialized. RTEMS
    66 initialization is complete, interrupts and tasking are enabled,
    67 but no device drivers are initialized.  This field may be NULL to
    68 indicate that the hook is not utilized.
     64routine that is invoked immediately before the
     65the device drivers and MPCI are initialized. RTEMS
     66initialization is complete but interrupts and tasking are disabled.
     67This field may be NULL to indicate that the hook is not utilized.
    6968
    7069@item postdriver_hook
    7170is the address of the user provided
    72 routine which is invoked with tasking enabled immediately after
    73 the MPCI and device drivers are initialized. RTEMS
    74 initialization is complete, interrupts and tasking are enabled,
    75 and the device drivers are initialized.  This field may be NULL
    76 to indicate that the hook is not utilized.
     71routine that is invoked immediately after the
     72the device drivers and MPCI are initialized. RTEMS
     73initialization is complete but interrupts and tasking are disabled.
     74This field may be NULL to indicate that the hook is not utilized.
    7775
    7876@item idle_task
  • doc/supplements/m68k/cputable.t

    r06fee20 rbc950e87  
    4848@table @code
    4949@item pretasking_hook
    50 is the address of the
    51 user provided routine which is invoked once RTEMS initialization
    52 is complete but before interrupts and tasking are enabled.  This
    53 field may be NULL to indicate that the hook is not utilized.
     50is the address of the user provided routine which is invoked
     51once RTEMS APIs are initialized.  This routine will be invoked
     52before any system tasks are created.  Interrupts are disabled.
     53This field may be NULL to indicate that the hook is not utilized.
    5454
    5555@item predriver_hook
    5656is the address of the user provided
    57 routine which is invoked with tasking enabled immediately before
    58 the MPCI and device drivers are initialized. RTEMS
    59 initialization is complete, interrupts and tasking are enabled,
    60 but no device drivers are initialized.  This field may be NULL to
    61 indicate that the hook is not utilized.
     57routine that is invoked immediately before the
     58the device drivers and MPCI are initialized. RTEMS
     59initialization is complete but interrupts and tasking are disabled.
     60This field may be NULL to indicate that the hook is not utilized.
    6261
    6362@item postdriver_hook
    6463is the address of the user provided
    65 routine which is invoked with tasking enabled immediately after
    66 the MPCI and device drivers are initialized. RTEMS
    67 initialization is complete, interrupts and tasking are enabled,
    68 and the device drivers are initialized.  This field may be NULL
    69 to indicate that the hook is not utilized.
     64routine that is invoked immediately after the
     65the device drivers and MPCI are initialized. RTEMS
     66initialization is complete but interrupts and tasking are disabled.
     67This field may be NULL to indicate that the hook is not utilized.
    7068
    7169@item idle_task
  • doc/supplements/powerpc/cputable.t

    r06fee20 rbc950e87  
    5555@table @code
    5656@item pretasking_hook
    57 is the address of the
    58 user provided routine which is invoked once RTEMS initialization
    59 is complete but before interrupts and tasking are enabled.  This
    60 field may be NULL to indicate that the hook is not utilized.
     57is the address of the user provided routine which is invoked
     58once RTEMS APIs are initialized.  This routine will be invoked
     59before any system tasks are created.  Interrupts are disabled.
     60This field may be NULL to indicate that the hook is not utilized.
    6161
    6262@item predriver_hook
    6363is the address of the user provided
    64 routine which is invoked with tasking enabled immediately before
    65 the MPCI and device drivers are initialized. RTEMS
    66 initialization is complete, interrupts and tasking are enabled,
    67 but no device drivers are initialized.  This field may be NULL to
    68 indicate that the hook is not utilized.
     64routine that is invoked immediately before the
     65the device drivers and MPCI are initialized. RTEMS
     66initialization is complete but interrupts and tasking are disabled.
     67This field may be NULL to indicate that the hook is not utilized.
    6968
    7069@item postdriver_hook
    7170is the address of the user provided
    72 routine which is invoked with tasking enabled immediately after
    73 the MPCI and device drivers are initialized. RTEMS
    74 initialization is complete, interrupts and tasking are enabled,
    75 and the device drivers are initialized.  This field may be NULL
    76 to indicate that the hook is not utilized.
     71routine that is invoked immediately after the
     72the device drivers and MPCI are initialized. RTEMS
     73initialization is complete but interrupts and tasking are disabled.
     74This field may be NULL to indicate that the hook is not utilized.
    7775
    7876@item idle_task
  • doc/supplements/sparc/cputable.t

    r06fee20 rbc950e87  
    4444@table @code
    4545@item pretasking_hook
    46 is the address of the
    47 user provided routine which is invoked once RTEMS initialization
    48 is complete but before interrupts and tasking are enabled.  This
    49 field may be NULL to indicate that the hook is not utilized.
     46is the address of the user provided routine which is invoked
     47once RTEMS APIs are initialized.  This routine will be invoked
     48before any system tasks are created.  Interrupts are disabled.
     49This field may be NULL to indicate that the hook is not utilized.
    5050
    5151@item predriver_hook
    5252is the address of the user provided
    53 routine which is invoked with tasking enabled immediately before
    54 the MPCI and device drivers are initialized. RTEMS
    55 initialization is complete, interrupts and tasking are enabled,
    56 but no device drivers are initialized.  This field may be NULL to
    57 indicate that the hook is not utilized.
     53routine that is invoked immediately before the
     54the device drivers and MPCI are initialized. RTEMS
     55initialization is complete but interrupts and tasking are disabled.
     56This field may be NULL to indicate that the hook is not utilized.
    5857
    5958@item postdriver_hook
    6059is the address of the user provided
    61 routine which is invoked with tasking enabled immediately after
    62 the MPCI and device drivers are initialized. RTEMS
    63 initialization is complete, interrupts and tasking are enabled,
    64 and the device drivers are initialized.  This field may be NULL
    65 to indicate that the hook is not utilized.
     60routine that is invoked immediately after the
     61the device drivers and MPCI are initialized. RTEMS
     62initialization is complete but interrupts and tasking are disabled.
     63This field may be NULL to indicate that the hook is not utilized.
    6664
    6765@item idle_task
  • doc/supplements/template/cputable.t

    r06fee20 rbc950e87  
    4848@table @code
    4949@item pretasking_hook
    50 is the address of the
    51 user provided routine which is invoked once RTEMS initialization
    52 is complete but before interrupts and tasking are enabled.  This
    53 field may be NULL to indicate that the hook is not utilized.
     50is the address of the user provided routine which is invoked
     51once RTEMS APIs are initialized.  This routine will be invoked
     52before any system tasks are created.  Interrupts are disabled.
     53This field may be NULL to indicate that the hook is not utilized.
    5454
    5555@item predriver_hook
    5656is the address of the user provided
    57 routine which is invoked with tasking enabled immediately before
    58 the MPCI and device drivers are initialized. RTEMS
    59 initialization is complete, interrupts and tasking are enabled,
    60 but no device drivers are initialized.  This field may be NULL to
    61 indicate that the hook is not utilized.
     57routine that is invoked immediately before the
     58the device drivers and MPCI are initialized. RTEMS
     59initialization is complete but interrupts and tasking are disabled.
     60This field may be NULL to indicate that the hook is not utilized.
    6261
    6362@item postdriver_hook
    6463is the address of the user provided
    65 routine which is invoked with tasking enabled immediately after
    66 the MPCI and device drivers are initialized. RTEMS
    67 initialization is complete, interrupts and tasking are enabled,
    68 and the device drivers are initialized.  This field may be NULL
    69 to indicate that the hook is not utilized.
     64routine that is invoked immediately after the
     65the device drivers and MPCI are initialized. RTEMS
     66initialization is complete but interrupts and tasking are disabled.
     67This field may be NULL to indicate that the hook is not utilized.
    7068
    7169@item idle_task
Note: See TracChangeset for help on using the changeset viewer.