From bc950e878a06243e272493eff8a9509b4e416483 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Thu, 19 Nov 1998 16:02:06 +0000 Subject: Applied updates from remote work while doing class. --- doc/bsp_howto/Makefile | 13 +- doc/bsp_howto/analog.t | 153 +++++++++++++++- doc/bsp_howto/bsp_howto.texi | 2 +- doc/bsp_howto/clock.t | 115 ++++++++++-- doc/bsp_howto/console.t | 336 ++++++++++++++++++++++++------------ doc/bsp_howto/discrete.t | 173 ++++++++++++++++++- doc/bsp_howto/init.t | 305 +++++++++++++++++++------------- doc/bsp_howto/network.t | 12 -- doc/bsp_howto/nvmem.t | 225 +++++++++++++++++++++++- doc/bsp_howto/rtc.t | 177 ++++++++++++++++++- doc/bsp_howto/shmsupp.t | 259 ++++++++++++++++++++++++++- doc/bsp_howto/support.t | 249 +++++++++++++++++++++++++- doc/bsp_howto/timer.t | 121 +++++++++---- doc/networking/driver.t | 2 +- doc/new_chapters/Makefile | 28 ++- doc/new_chapters/files.t | 129 ++++++++++++++ doc/new_chapters/gen_section | 26 +++ doc/new_chapters/posix_users.texi | 10 ++ doc/new_chapters/signal.t | 2 + doc/posix1003.1/Makefile | 2 +- doc/posix1003.1/ch06.t | 2 +- doc/posix1003.1/ch14.t | 10 +- doc/started/Makefile | 4 +- doc/supplements/hppa1_1/cputable.t | 26 ++- doc/supplements/i386/cputable.t | 26 ++- doc/supplements/i960/cputable.t | 26 ++- doc/supplements/m68k/cputable.t | 26 ++- doc/supplements/powerpc/cputable.t | 26 ++- doc/supplements/sparc/cputable.t | 26 ++- doc/supplements/template/cputable.t | 26 ++- 30 files changed, 2115 insertions(+), 422 deletions(-) (limited to 'doc') diff --git a/doc/bsp_howto/Makefile b/doc/bsp_howto/Makefile index f61d8b5739..3af731dc2d 100644 --- a/doc/bsp_howto/Makefile +++ b/doc/bsp_howto/Makefile @@ -44,7 +44,7 @@ $(PROJECT).ps: $(PROJECT).dvi # run texi2dvi twice to generate the xref's properly. $(PROJECT).dvi: $(FILES) $(TEXI2DVI) $(PROJECT).texi - $(TEXI2DVI) $(PROJECT).texi + texi2dvi $(PROJECT).texi html: dirs $(FILES) -mkdir -p $(WWW_INSTALL)/$(PROJECT) @@ -55,7 +55,14 @@ clean: rm -f *.o $(PROG) *.txt core rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE) rm -f $(PROJECT) $(PROJECT)-* $(GENERATED_FILES) - rm -f *.fixed _* + rm -f *.fixed _* network.t + +# +# Grab the chapter on writing a network device driver. +# +network.t: + ln -s ../networking/driver.t network.t + # # Process Automatically Generated Files @@ -79,7 +86,7 @@ makefiles.texi: makefiles.t Makefile linkcmds.texi: linkcmds.t Makefile $(BMENU) -p "Makefiles Creating a New BSP Make Customization File" \ -u "Top" \ - -n "Required Support Routines" ${*}.t + -n "Miscellaneous Support Files" ${*}.t support.texi: support.t Makefile $(BMENU) -p "Linker Script Initialized Data" \ diff --git a/doc/bsp_howto/analog.t b/doc/bsp_howto/analog.t index 8c402ad5c9..34cee23f65 100644 --- a/doc/bsp_howto/analog.t +++ b/doc/bsp_howto/analog.t @@ -8,5 +8,156 @@ @chapter Analog Driver -XXX FILL ME IN +The Analog driver is responsible for providing an +interface to Digital to Analog Converters (DACs) and +Analog to Digital Converters (ADCs). The capabilities provided +by this class of device driver are: + +@itemize @bullet +@item Initialize an Analog Board +@item Open a Particular Analog +@item Close a Particular Analog +@item Read from a Particular Analog +@item Write to a Particular Analog +@item Reset DACs +@item Reinitialize DACS +@end itemize + +Most analog devices are found on I/O cards that support multiple +DACs or ADCs on a single card. + +There are currently no analog device drivers included in the +RTEMS source tree. The information provided in this chapter +is based on drivers developed by OAR Corporation personnel +for applications using RTEMS. It is hoped that this +driver model information can form the basis for a standard +analog driver model that can be supported in future RTEMS +distribution. + +@section Major and Minor Numbers + +The @b{major} number of a device driver is its index in the +RTEMS Device Address Table. + +A @b{minor} number is associated with each device instance +managed by a particular device driver. An RTEMS minor number +is an @code{unsigned32} entity. Convention calls +dividing the bits in the minor number down into categories +like the following: + +@itemize @bullet + +@item @b{board} - indicates the board a particular device is located on +@item @b{port} - indicates the particular device on a board. + +@end itemize + +From the above, it should be clear that a single device driver +can support multiple copies of the same board in a single system. +The minor number is used to distinguish the devices. + +@section Analog Driver Configuration + +There is not a standard analog driver configuration table but some +fields are common across different drivers. The analog driver +configuration table is typically an array of structures with each +structure containing the information for a particular board. +The following is a list of the type of information normally required +to configure an analog board: + +@table @b +@item board_offset +is the base address of a board. + +@item DAC_initial_values +is an array of the voltages that should be written to each DAC +during initialization. This allows the driver to start the board +in a known state. + +@end table + +@section Initialize an Analog Board + +At system initialization, the analog driver's initialization entry point +will be invoked. As part of initialization, the driver will perform +whatever board initializatin is required and then set all +outputs to their configured initial state. + +The analog driver may register a device name for each DAC and ADC in +the system. + +@section Open a Particular Analog + +This is the driver open call. Usually this call does nothing other than +validate the minor number. + +With some drivers, it may be necessary to allocate memory when a particular +device is opened. If that is the case, then this is often the place +to do this operation. + +@section Close a Particular Analog + +This is the driver close call. Usually this call does nothing. + +With some drivers, it may be necessary to allocate memory when a particular +device is opened. If that is the case, then this is the place +where that memory should be deallocated. + +@section Read from a Particular Analog + +This corresponds to the driver read call. After validating the minor +number and arguments, this call reads the indicated device. Most analog +devices store the last value written to a DAC. Since DACs are output +only devices, saving the last written value gives the appearance that +DACs can be read from also. If the device is an ADC, then it is sampled. + +@b{NOTE:} Many boards have multiple analog inputs but only one ADC. On +these boards, it will be necessary to provide some type of mutual exclusion +during reads. On these boards, there is a MUX which must be switched +before sampling the ADC. After the MUX is switched, the driver must +delay some short period of time (usually microseconds) before the +signal is stable and can be sampled. To make matters worse, some ADCs +cannot respond to wide voltage swings in a single sample. On these +ADCs, one must do two samples when the voltage swing is too large. +On a practical basis, this means that the driver usually ends up +double sampling the ADC on these systems. + +The value returned is a single precision floating point number +representing the voltage read. This value is stored in the +@code{argument_block} passed in to the call. By returning the +voltage, the caller is freed from having to know the number of +bits in the analog and board dependent conversion algorithm. + +@section Write to a Particular Analog + +This corresponds to the driver write call. After validating the minor +number and arguments, this call writes the indicated device. If the +specified device is an ADC, then an error is usually returned. + +The value written is a single precision floating point number +representing the voltage to be written to the specified DAC. +This value is stored in the @code{argument_block} passed in to the +call. By passing the voltage to the device driver, the caller is +freed from having to know the number of bits in the analog +and board dependent conversion algorithm. + +@section Reset DACs + +This is one of the IOCTL functions supported by the I/O control +device driver entry point. When this IOCTL function is invoked, +all of the DACs are written to 0.0 volts. + +@section Reinitialize DACS + +This is one of the IOCTL functions supported by the I/O control +device driver entry point. When this IOCTL function is invoked, +all of the DACs are written with the initial value configured +for this device. + +@section Get Last Written Values + +This is one of the IOCTL functions supported by the I/O control +device driver entry point. When this IOCTL function is invoked, +the last value written to the specified output word along with +a timestamp of when the last write was performed. diff --git a/doc/bsp_howto/bsp_howto.texi b/doc/bsp_howto/bsp_howto.texi index bf9dc23960..f2e6e6342b 100644 --- a/doc/bsp_howto/bsp_howto.texi +++ b/doc/bsp_howto/bsp_howto.texi @@ -89,7 +89,7 @@ This is the online version of the Getting Started with RTEMS for C/C++ Users. * Target Dependent Files:: * Makefiles:: * Linker Script:: -* Required Support Routines:: +* Miscellaneous Support Files:: * Initialization Code:: * Console Driver:: * Clock Driver:: diff --git a/doc/bsp_howto/clock.t b/doc/bsp_howto/clock.t index 918f6331b2..e6bd4f3cb0 100644 --- a/doc/bsp_howto/clock.t +++ b/doc/bsp_howto/clock.t @@ -10,37 +10,120 @@ @section Introduction -The clock driver aims at giving a steady time basis to the kernel, so that -the RTEMS primitives that need a clock tick work properly. +The purpose of the clock driver is to provide a steady time +basis to the kernel, so that the RTEMS primitives that need +a clock tick work properly. See the @code{Clock Manager} chapter +of the @b{RTEMS Application C User's Guide} for more details. -The clock driver is located in the clock directory of the BSP. +The clock driver is located in the @code{clock} directory of the BSP. -@section Primitives +@section Clock Driver Global Variables -@subsection Initialization +@subsection Major and Minor Number -The major and minor numbers of the clock driver can be made available to -the others, such as the Shared Memory Driver. +The major and minor numbers of the clock driver are made available via +the following variables. -Then you have to program your integrated processor periodic interval timer -so that an interrupt is generated every m microseconds, where m = -BSP_Configuration.microseconds_per_tick. Sometimes the periodic interval +@itemize @bullet +@item rtems_device_major_number rtems_clock_major; +@item rtems_device_minor_number rtems_clock_minor; +@end itemize + +The clock device driver is responsible for declaring and +initializing these variables. These variables are used +by other RTEMS components -- notably the Shared Memory Driver. + +@b{NOTE:} In a future RTEMS version, these variables may be replaced +with the clock device driver registering @b{/dev/clock}. + +@subsection Ticks Counter + +Most of the clock device drivers provide a global variable +that is simply a count of the number of clock driver interrupt service +routines that have occured. This information is valuable when debugging +a system. This variable is declared as follows: + +@example +volatile rtems_unsigned32 Clock_driver_ticks; +@end example + +@section Initialization + +The initialization routine is responsible for +programming the hardware that will periodically +generate an interrupt. A programmable interval timer is commonly +used as the source of the clock tick. + +The device should be programmed such that an interrupt is generated +every @i{m} microseconds, where @i{m} is equal to +@code{BSP_Configuration.microseconds_per_tick}. Sometimes the periodic interval timer can use a prescaler so you have to look carefully at your user's manual to determine the correct value. -You must use the RTEMS primitive to put your clock interrupt routine in -the VBR: +You must use the RTEMS primitive @code{rtems_interrupt_catch} to install +your clock interrupt service routine: @example -rtems_interrupt_catch (InterruptHandler, CONSOLE_VECTOR, &old_handler); +rtems_interrupt_catch (Clock_ISR, CLOCK_VECTOR, &old_handler); @end example -@subsection The Clock Interrupt Subroutine +Since there is currently not a driver entry point invoked at system +shutdown, many clock device drivers use the @code{atexit} routine +to schedule their @code{Clock_exit} routine to execute when the +system is shutdown. + +By convention, many of the clock drivers do not install the clock +tick if the @code{ticks_per_timeslice} field of the Configuration +Table is 0. + +@section System shutdown + +Many drivers provide the routine @code{Clock_exit} that is scheduled +to be run during system shutdown via the @code{atexit} routine. +The @code{Clock_exit} routine will disable the clock tick source +if it was enabled. This can be used to prevent clock ticks after the +system is shutdown. + +@section Clock Interrupt Subroutine It only has to inform the kernel that a ticker has elapsed, so call : @example -rtems_clock_tick(); +@group +rtems_isr Clock_isr( rtems_vector_number vector ) +@{ + invoke the rtems_clock_tick() directive to announce the tick + if necessary for this hardware + reload the programmable timer +@} +@end group @end example +@section IO Control + +The clock driver must supply a handler for the IO control device driver +entry point. This functionality is used by other components -- notably +the Shared Memory Driver to install a wrapper for the clock interrupt +service routine. The following shows the functionality required: + +@example +@group +rtems_device_driver Clock_control( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *pargp +) +@{ + error check the argument pointer parameter + + if the command is "ISR" + invoke the clock interrupt service routine + else if the command is "NEW" + install the requested handler +@} +@end group +@end example + + + + diff --git a/doc/bsp_howto/console.t b/doc/bsp_howto/console.t index 09d8b25640..0b94cede70 100644 --- a/doc/bsp_howto/console.t +++ b/doc/bsp_howto/console.t @@ -10,16 +10,22 @@ @section Introduction -This chapter describes how to do a console driver using RTEMS Termios -support. - -The serial driver is called as soon as printf/scanf or read/write kind of -input/output are needed. There are two main functioning modes: +This chapter describes the operation of a console driver using +the RTEMS POSIX Termios support. Traditionally RTEMS has referred +to all serial device drivers as console device drivers. A +console driver can be used to do raw data processing in addition +to the "normal" standard input and output device functions required +of a console. + +The serial driver may be called as the consequence of a C Library +call such as @code{printf} or @code{scanf} or directly via the +@code{read} or @code{write} system calls. +There are two main functioning modes: @itemize @bullet @item console: formatted input/output, with special characters (end of -line, tabulations, etc...) recognition and processing, +line, tabulations, etc.) recognition and processing, @item raw: permits raw data processing. @@ -30,16 +36,20 @@ of data, but Termios permits having only one driver. @section Termios -Termios is a standard for terminal management, included in several Unix -versions. Termios is good because: +Termios is a standard for terminal management, included in the POSIX 1003.1b +standard. It is commonly provided on UNIX implementations. +Having RTEMS support for Termios is beneficial: @itemize @bullet -@item from the user's side: primitives to access the terminal and change -configuration settings are the same under Unix and Rtems. +@item from the user's side because it provides standard primitive operations +to access the terminal and change configuration settings. These operations +are the same under Unix and Rtems. -@item from the BSP developer's side: it frees you from dealing with buffer -states and mutual exclusions on them. +@item from the BSP developer's side because it frees the +developer from dealing with buffer states and mutual exclusions on them. +Early RTEMS console device drivers also did their own special +character processing. @end itemize @@ -54,8 +64,16 @@ Timeout. @end itemize -For more information on Termios, type man termios in your Unix box or go -to http://www.freebsd.org/cgi/man.cgi. +At this time, RTEMS documentation does not include a thorough discussion +of the Termios functionality. For more information on Termios, +type @code{man termios} on a Unix box or point a web browser +at +@ifset use-html +@href{http://www.freebsd.org/cgi/man.cgi,,,http://www.freebsd.org/cgi/man.cgi}. +@end ifset +@ifclear use-html +@code{http://www.freebsd.org/cgi/man.cgi}. +@end ifclear @section Driver Functioning Modes @@ -64,130 +82,203 @@ Asynchronous Receiver-Transmitter, i.e. the serial chip): @itemize @bullet -@item polling mode: the processor blocks on sending/receiving characters. -This mode is not powerful, but is necessary when one wants to print an -error message when the board hung. This is also the most simple mode to -program, - -@item interrupt mode: the processor doesn't block on sending/receiving -characters. Two buffers (one for the in-going characters, the others for -the characters to be sent) are used. An interrupt is raised as soon as a -character is in the UART. Then the int errupt subroutine insert the -character at the input buffer queue. When a character is asked for input, -this at the head of the buffer is returned. When characters have to be -sent, one have to put the first characters (the number depends on the -UART) in th e UART. Then an interrupt is raised when all the characters -have been emitted. The interrupt subroutine has to send the characters -remaining in the output buffer the same way. +@item polled mode +@item interrupt driven mode @end itemize +In polled mode, the processor blocks on sending/receiving characters. +This mode is not the most efficient way to utilize the UART. But +polled mode is usually necessary when one wants to print an +error message in the event of a fatal error such as al fatal error +in the BSP. This is also the simplest mode to +program. Polled mode is generally preferred if the serial port is +to be used primarily as a debug console. In a simple polled driver, +the software will continuously check the status of the UART when +it is reading or writing to the UART. Termios improves on this +by delaying the caller for 1 clock tick between successive checks +of the UART on a read operation. + +In interrupt driven mode, the processor does not block on sending/receiving +characters. Data is buffered between the interrupt service routine +and application code. Two buffers are used to insulate the application +from the relative slowness of the serial device. One of the buffers is +used for incoming characters, while the other is used for outgoing characters. + +An interrupt is raised when a character is received by the UART. +The interrupt subroutine places the incoming character at the end +of the input buffer. When an application asks for input, +the characters at the front of the buffer are returned. + +When the application prints to the serial device, the outgoing characters +are placed at the end of the output buffer. The driver will place +one or more characters in the UART (the exact number depends on the UART) +An interrupt will be raised when all the characters have been transmitted. +The interrupt service routine has to send the characters +remaining in the output buffer the same way. When the transmitting side +of the UART is idle, it is typically necessary to prime the transmitter +before the first interrupt will occur. + @section Serial Driver Functioning Overview -Figure 5 is an attempt of showing how a Termios driven serial driver works : +The following Figure shows how a Termios driven serial driver works: + +@example +This figure needs to be inserted in this document. +@end example + +The following list describes the basic flow. @itemize @bullet @item the application programmer uses standard C library call (printf, scanf, read, write, etc.), -@item C library (in fact that's Cygnus Newlib) calls RTEMS procedure: glue -is made in newlib*.c files which can be found under -$RTEMS_ROOT/c/src/lib/libc directory, +@item C library (in fact that's Cygnus Newlib) calls RTEMS +system call interface. This code can be found in the +@code{c/src/lib/libc} directory. -@item Glue code calls your serial driver entry routines. +@item Glue code calls the serial driver entry routines. @end itemize @subsection Termios and Polled I/O -You have to point Termios out which functions are used for simple -character input/output: - +The following functions are provided by the driver and invoked by +Termios for simple character input/output. The specific names of +these routines are not important as Termios invokes them indirectly +via function pointers. -Function +@subsubsection pollWrite -Description +The @code{pollWrite} routine is responsible for writing @code{len} characters +from @code{buf} to the serial device specified by @code{minor}. @example +@group int pollWrite (int minor, const char *buf, int len) - -for (i=0; i. - -@section RTEMS initialization procedure - -The RTEMS initialization procedure is described in the 3rd chapter of the -C user's manual . Please read it carefully. - -There are a few BSP specific functions called from the initialization -manager. They can be found in the startup directory of the BSP. - -@table @b - -@item bspstart.c - -It starts the application. It includes application, board, and monitor -specific initialization and configuration. - -@item bspstart.c - -@table @b -@item bsp_pretasking_hook - -It starts libc support (needed to allocate some memory using C primitive -malloc for example). Heap size must be passed in argument, this is the one -which is defined in the linkcmds (cf. 5.) - - -@end table - -@item bspclean.c - -@table @b - -@item bsp_cleanup - -Return control to the monitor. - -@end table - -@end table - -@section Drivers initialization - -The Driver Address Table is part of the RTEMS configuration table. It -defines RTEMS drivers entry points (initialization, open, close, read, -write, and control). For more information about this table, check C User's -manual chapter 21 section 6 . - -The RTEMS initialization procedure calls the initialization function for -every driver defined in the RTEMS Configuration Table (this permits to add -only the drivers needed by the application). - -All these primitives have a major and a minor number as arguments: - -@itemize @bullet - -@item the major number refers to the driver type, - -@item the minor number is used to control two peripherals with the same -driver (for instance, we define only one major number for the serial -driver, but two minor numbers for channel A and B if there are two -channels in the UART). - -@end itemize +The RTEMS configuration table is application dependent, which means that +one has to provide one per application. It is usually defined +by defining macros and including the header file @code{}. +In simple applications such as the tests provided with RTEMS, it is +commonly found in the main module of the application. For more complex +applications, it may be in a file by itself. + +The header file @code{} defines a constant table named +@code{Configuration}. It is common practice for the BSP to copy +this table into a modifiable copy named @code{BSP_Configuration}. +This copy of the table is modified to define the base address of the +RTEMS Executive Workspace as well as to reflect any BSP and +device driver requirements not automatically handled by the application. + +For more information on the RTEMS Configuration Table, refer to the +@b{RTEMS Application C User's Guide}. diff --git a/doc/bsp_howto/network.t b/doc/bsp_howto/network.t index 2721898ab1..e69de29bb2 100644 --- a/doc/bsp_howto/network.t +++ b/doc/bsp_howto/network.t @@ -1,12 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-1998. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c $Id$ -@c - -@chapter Networking Driver - -XXX FILL ME IN - diff --git a/doc/bsp_howto/nvmem.t b/doc/bsp_howto/nvmem.t index 070621ddca..eda65f93a5 100644 --- a/doc/bsp_howto/nvmem.t +++ b/doc/bsp_howto/nvmem.t @@ -8,5 +8,228 @@ @chapter Non-Volatile Memory Driver -XXX FILL ME IN +The Non-Volatile driver is responsible for providing an +interface to various types of non-volatile memory. These +types of memory include, but are not limited to, Flash, EEPROM, +and battery backed RAM. The capabilities provided +by this class of device driver are: + +@itemize @bullet +@item Initialize the Non-Volatile Memory Driver +@item Optional Disable Read and Write Handlers +@item Open a Particular Memory Partition +@item Close a Particular Memory Partition +@item Read from a Particular Memory Partition +@item Write to a Particular Memory Partition +@item Erase the Non-Volatile Memory Area +@end itemize + +There is currently only one non-volatile device driver included in the +RTEMS source tree and it does not adhere to this device driver model. +The information provided in this chapter is based on drivers developed +by OAR Corporation personnel for applications using RTEMS. It is +hoped that this driver model information can form the basis for a standard +non-volatile memory driver model that can be supported in future RTEMS +distribution. + +@section Major and Minor Numbers + +The @b{major} number of a device driver is its index in the +RTEMS Device Address Table. + +A @b{minor} number is associated with each device instance +managed by a particular device driver. An RTEMS minor number +is an @code{unsigned32} entity. Convention calls +dividing the bits in the minor number down into categories +that specify an area of non-volatile memory and a partition +with that area. This results in categories +like the following: + +@itemize @bullet + +@item @b{area} - indicates a block of non-volatile memory +@item @b{partition} - indicates a particular address range with an area + +@end itemize + +From the above, it should be clear that a single device driver +can support multiple types of non-volatile memory in a single system. +The minor number is used to distinguish the types of memory and +blocks of memory used for different purposes. + +@section Non-Volatile Memory Driver Configuration + +There is not a standard non-volatile driver configuration table but some +fields are common across different drivers. The non-volatile memory driver +configuration table is typically an array of structures with each +structure containing the information for a particular area of +non-volatile memory. +The following is a list of the type of information normally required +to configure each area of non-volatile memory + +@table @b +@item memory_type +is the type of memory device in this area. Choices are battery backed RAM, +EEPROM, Flash, or an optional user-supplied type. If the user-supplied type +is configured, then the user is responsible for providing a set of +routines to program the memory. + +@item memory +is the base address of this memory area. + +@item attributes +is a pointer to a memory type specific attribute block. Some of +the fields commonly contained in this memory type specific attribute +structure area: + +@table @b +@item use_protection_algorithm +is set to TRUE to indicate that the protection (i.e. locking) algorithm +should be used for this area of non-volatile memory. A particular +type of non-volatile memory may not have a protection algorithm. + +@item access +is an enumerated type to indicate the organization of the memory +devices in this memory area. The following is a list of the +access types supported by the current driver implementation: + +@itemize @bullet +@item simple unsigned8 +@item simple unsigned16 +@item simple unsigned32 +@item simple unsigned64 +@item single unsigned8 at offset 0 in an unsigned16 +@item single unsigned8 at offset 1 in an unsigned16 +@item single unsigned8 at offset 0 in an unsigned32 +@item single unsigned8 at offset 1 in an unsigned32 +@item single unsigned8 at offset 2 in an unsigned32 +@item single unsigned8 at offset 3 in an unsigned32 +@end itemize + +@item depth +is the depth of the progamming FIFO on this particular chip. Some +chips, particularly EEPROMs, have the same programming algorithm but +vary in the depth of the amount of data that can be programmed in a single +block. + +@end table + +@item number_of_partitions +is the number of logical partitions within this area. + +@item Partitions +is the address of table that contains an entry to describe each +partition in this area. Fields within each element of this +table are defined as follows: + +@table @b + +@item offset +is the offset of this partition from the base address of this area. + +@item length +is the length of this partition. + +@end table +@end table + +By dividing an area of memory into multiple partitions, it is possible +to easily divide the non-volatile memory for different purposes. + +@section Initialize the Non-Volatile Memory Driver + +At system initialization, the non-volatile memory driver's +initialization entry point will be invoked. As part of +initialization, the driver will perform +whatever initializatin is required on each non-volatile memory area. + +The discrete I/O driver may register devices name for memory +partitions of particular interest to the system. Normally this +will be restricted to the device "/dev/nv_memory" to indicate +the entire device driver. + +@section Disable Read and Write Handlers + +Depending on the target's non-volatile memory configuration, it may be +possible to write to a status register and make the memory area completely +inaccessible. This is target dependent and beyond the standard capabilities +of any memory type. The user has the optional capability to provide +handlers to disable and enable access to a partiticular memory area. + +@section Open a Particular Memory Partition + +This is the driver open call. Usually this call does nothing other than +validate the minor number. + +With some drivers, it may be necessary to allocate memory when a particular +device is opened. If that is the case, then this is often the place +to do this operation. + +@section Close a Particular Memory Partition + +This is the driver close call. Usually this call does nothing. + +With some drivers, it may be necessary to allocate memory when a particular +device is opened. If that is the case, then this is the place +where that memory should be deallocated. + +@section Read from a Particular Memory Partition + +This corresponds to the driver read call. After validating the minor +number and arguments, this call enables reads from the specified +memory area by invoking the user supplied "enable reads handler" +and then reads the indicated memory area. When +invoked the @code{argument_block} is actually a pointer to the following +structure type: + +@example +@group +typedef struct @{ + rtems_unsigned32 offset; + void *buffer; + rtems_unsigned32 length; + rtems_unsigned32 status; +@} Non_volatile_memory_Driver_arguments; +@end group +@end example + +The driver reads @code{length} bytes starting at @code{offset} into +the partition and places them at @code{buffer}. The result is returned +in @code{status}. + +After the read operation is complete, the user supplied "disable reads handler" +is invoked to protect the memory area again. + +@section Write to a Particular Memory Partition + +This corresponds to the driver write call. After validating the minor +number and arguments, this call enables writes to the specified +memory area by invoking the "enable writes handler", then unprotecting +the memory area, and finally actually writing to the indicated memory +area. When invoked the @code{argument_block} is actually a pointer to +the following structure type: + +@example +@group +typedef struct @{ + rtems_unsigned32 offset; + void *buffer; + rtems_unsigned32 length; + rtems_unsigned32 status; +@} Non_volatile_memory_Driver_arguments; +@end group +@end example + +The driver writes @code{length} bytes from @code{buffer} and +writes them to the non-volatile memory starting at @code{offset} into +the partition. The result is returned in @code{status}. + +After the write operation is complete, the "disable writes handler" +is invoked to protect the memory area again. + +@section Erase the Non-Volatile Memory Area + +This is one of the IOCTL functions supported by the I/O control +device driver entry point. When this IOCTL function is invoked, +the specified area of non-volatile memory is erased. diff --git a/doc/bsp_howto/rtc.t b/doc/bsp_howto/rtc.t index f0e3bccabb..6134452dd7 100644 --- a/doc/bsp_howto/rtc.t +++ b/doc/bsp_howto/rtc.t @@ -8,5 +8,180 @@ @chapter Real-Time Clock Driver -XXX FILL ME IN +@section Introduction + +The Real-Time Clock (@b{RTC}) driver is responsible for providing an +interface to an @b{RTC} device. [NOTE: In this chapter, the abbreviation +@b{TOD} is used for @b{Time of Day}.] The capabilities provided by this +driver are: + +@itemize @bullet +@item Set the RTC TOD to RTEMS TOD +@item Set the RTEMS TOD to the RTC TOD +@item Get the RTC TOD +@item Set the RTC TOD to the Specified TOD +@item Get the Difference Between the RTEMS and RTC TOD +@end itemize + +The reference implementation for a real-time clock driver can +be found in @code{c/src/lib/libbsp/shared/tod.c}. This driver +is based on the libchip concept and can be easily configured +to work with any of the RTC chips supported by the RTC +chip drivers in the directory @code{c/src/lib/lib/libchip/rtc}. +There is a README file in this directory for each supported +RTC chip. Each of these README explains how to configure the +shared libchip implementation of the RTC driver for that particular +RTC chip. + +The DY-4 DMV177 BSP uses the shared libchip implementation of the RTC +driver. Its @code{RTC_Table} configuration table can be found in +@code{c/src/lib/libbsp/powerpc/dmv177/tod/config.c}. + +@section Initialization + +The @code{rtc_initialize} routine is responsible for initializing the +RTC chip so it can be used. The shared libchip implementation of this +driver supports multiple RTCs and bases its initialization order on +the order the chips are defined in the @code{RTC_Table}. Each chip +defined in the table may or may not be present on this particular board. +It is the responsibility of the @code{deviceProbe} to indicate the +presence of a particular RTC chip. The first RTC found to be present +is considered the preferred RTC. + +In the shared libchip based implementation +of the driver, the following actions are performed: + +@example +@group +rtems_device_driver rtc_initialize( + rtems_device_major_number major, + rtems_device_minor_number minor_arg, + void *arg +) +@{ + for each RTC configured in RTC_Table + if the deviceProbe for this RTC indicates it is present + set RTC_Minor to this device + set RTC_Present to TRUE + break out of this loop + + if RTC_Present is not TRUE + return RTEMS_INVALID_NUMBER to indicate that no RTC is present + + register this minor number as the "/dev/rtc" + + perform the deviceInitialize routine for the preferred RTC chip + + for RTCs past this one in the RTC_Table + if the deviceProbe for this RTC indicates it is present + perform the deviceInitialize routine for this RTC chip + register the configured name for this RTC +@} +@end group +@end example + +The @code{deviceProbe} routine returns TRUE if the device +configured by this entry in the @code{RTC_Table} is present. +This configuration scheme allows one to support multiple versions +of the same board with a single BSP. For example, if the first +generation of a board had Vendor A's RTC chip and the second +generation had Vendor B's RTC chip, RTC_Table could contain +information for both. The @code{deviceProbe} configured +for Vendor A's RTC chip would need to return TRUE if the +board was a first generation one. The @code{deviceProbe} +routines are very board dependent. + +@section setRealTimeToRTEMS + +The @code{setRealTimeToRTEMS} routine sets the current RTEMS TOD to that +of the preferred RTC. + +@example +@group +void setRealTimeToRTEMS(void) +@{ + if no RTCs are present + return + + invoke the deviceGetTime routine for the preferred RTC + set the RTEMS TOD using rtems_clock_set +@} +@end group +@end example + +@section setRealTimeFromRTEMS + +The @code{setRealTimeFromRTEMS} routine sets the preferred RTC TOD to the +current RTEMS TOD. + +@example +@group +void setRealTimeFromRTEMS(void) +@{ + if no RTCs are present + return + + obtain the RTEMS TOD using rtems_clock_get + invoke the deviceSetTime routine for the preferred RTC +@} +@end group +@end example + +@section getRealTime + +The @code{getRealTime} returns the preferred RTC TOD to the +caller. + +@example +@group +void getRealTime( rtems_time_of_day *tod ) +@{ + if no RTCs are present + return + + invoke the deviceGetTime routine for the preferred RTC +@} +@end group +@end example + +@section setRealTime + +The @code{setRealTime} routine sets the preferred RTC TOD to the +TOD specified by the caller. + +@example +@group +void setRealTime( rtems_time_of_day *tod ) +@{ + if no RTCs are present + return + + invoke the deviceSetTime routine for the preferred RTC +@} +@end group +@end example + +@section checkRealTime + +The @code{checkRealTime} routine returns the number of seconds +difference between the RTC TOD and the current RTEMS TOD. + +@example +@group +int checkRealTime( void ) +@{ + if no RTCs are present + return -1 + + + obtain the RTEMS TOD using rtems_clock_get + get the TOD from the preferred RTC using the deviceGetTime routine + + convert the RTEMS TOD to seconds + convert the RTC TOD to seconds + + return the RTEMS TOD in seconds - RTC TOD in seconds +@} +@end group +@end example diff --git a/doc/bsp_howto/shmsupp.t b/doc/bsp_howto/shmsupp.t index 96e0f31ab2..1e619ae2dc 100644 --- a/doc/bsp_howto/shmsupp.t +++ b/doc/bsp_howto/shmsupp.t @@ -8,5 +8,262 @@ @chapter Shared Memory Support Driver -XXX FILL ME IN +The Shared Memory Support Driver is responsible for providing glue +routines and configuration information required by the Shared +Memory Multiprocessor Communications Interface (MPCI). The +Shared Memory Support Driver tailors the portable Shared +Memory Driver to a particular target platform. + +This driver is only required in shared memory multiprocessing +systems that use the RTEMS mulitprocessing support. For more +information on RTEMS multiprocessing capabilities and the +MPCI, refer to the @b{Multiprocessing Manager} chapter +of the @b{RTEMS Application C User's Guide}. + +@section Shared Memory Configuration Table + +The Shared Memory Configuration Table is defined in the following +structure: + +@example +@group +typedef volatile rtems_unsigned32 vol_u32; + +typedef struct @{ + vol_u32 *address; /* write here for interrupt */ + vol_u32 value; /* this value causes interrupt */ + vol_u32 length; /* for this length (0,1,2,4) */ +@} Shm_Interrupt_information; + +struct shm_config_info @{ + vol_u32 *base; /* base address of SHM */ + vol_u32 length; /* length (in bytes) of SHM */ + vol_u32 format; /* SHM is big or little endian */ + vol_u32 (*convert)(); /* neutral conversion routine */ + vol_u32 poll_intr; /* POLLED or INTR driven mode */ + void (*cause_intr)( rtems_unsigned32 ); + Shm_Interrupt_information Intr; /* cause intr information */ +@}; + +typedef struct shm_config_info shm_config_table; +@end group +@end example + +where the fields are defined as follows: + +@table @b +@item base +is the base address of the shared memory buffer used to pass +messages between the nodes in the system. + +@item length +is the length (in bytes) of the shared memory buffer used to pass +messages between the nodes in the system. + +@item format +is either SHM_BIG or SHM_LITTLE to indicate that the neutral format +of the shared memory area is big or little endian. The format +of the memory should be chosen to match most of the inter-node traffic. + +@item convert +is the address of a routine which converts from native format to +neutral format. Ideally, the neutral format is the same as the +native format so this routine is quite simple. + +@item poll_intr +is either INTR_MODE or POLLED_MODE to indicate how the node will be +informed of incoming messages. + +@item cause_intr + +@item Intr +is the information required to cause an interrupt on a node. This +structure contains the following fields: +@table @b +@item address +is the address to write at to cause an interrupt on that node. +For a polled node, this should be NULL. + +@item value +is the value to write to cause an interrupt. + +@item length +is the length of the entity to write on the node to cause an interrupt. +This can be 0 to indicate polled operation, 1 to write a byte, 2 to +write a sixteen-bit entity, and 4 to write a thirty-two bit entity. +@end table +@end table + +@section Primitives + +@subsection Convert Address + +The @code{Shm_Convert_address} is responsible for converting an address +of an entity in the shared memory area into the address that should be +used from this node. Most targets will simply return the address +passed to this routine. However, some target boards will have a special +window onto the shared memory. For example, some VMEbus boards have +special address windows to access addresses that are normally reserved +in the CPU's address space. + +@example +@group +void *Shm_Convert_address( void *address ) +@{ + return the local address version of this bus address +@} +@end group +@end example + +@subsection Get Configuration + +The @code{Shm_Get_configuration} routine is responsible for filling in the +Shared Memory Configuration Table passed to it. + +@example +@group +void Shm_Get_configuration( + rtems_unsigned32 localnode, + shm_config_table **shmcfg +) +@{ + fill in the Shared Memory Configuration Table +@} +@end group +@end example + +@subsection Locking Primitives + +This is a collection of routines that are invoked by the portable +part of the Shared Memory Driver to manage locks in the shared +memory buffer area. Accesses to the shared memory must be +atomic. Two nodes in a multiprocessor system must not be manipulating +the shared data structures simultaneously. The locking primitives +are used to insure this. + +To avoid deadlock, local processor interrupts should be disabled the entire +time the locked queue is locked. + +The locking primitives operate on the lock +@code{field} of the @code{Shm_Locked_queue_Control} +data structure. This structure is defined as follows: + +@example +@group +typedef struct @{ + vol_u32 lock; /* lock field for this queue */ + vol_u32 front; /* first envelope on queue */ + vol_u32 rear; /* last envelope on queue */ + vol_u32 owner; /* receiving (i.e. owning) node */ +@} Shm_Locked_queue_Control; +@end group +@end example + +where each field is defined as follows: + +@table @b +@item lock +is the lock field. Every node in the system must agree on how this +field will be used. Many processor families provide an atomic +"test and set" instruction that is used to manage this field. + +@item front +is the index of the first message on this locked queue. + +@item rear +is the index of the last message on this locked queue. + +@item owner +is the node number of the node that currently has this structure locked. + +@end table + +@subsubsection Initializing a Shared Lock + +The @code{Shm_Initialize_lock} routine is responsible for +initializing the lock field. This routines usually is implemented +as follows: + +@example +@group +void Shm_Initialize_lock( + Shm_Locked_queue_Control *lq_cb +) +@{ + lq_cb->lock = LQ_UNLOCKED; +@} +@end group +@end example + +@subsubsection Acquiring a Shared Lock + +The @code{Shm_Lock} routine is responsible for +acquiring the lock field. Interrupts should be +disabled while that lock is acquired. If the lock +is currently unavailble, then the locking routine +should delay a few microseconds to allow the other +node to release the lock. Doing this reduces bus contention +for the lock. This routines usually is implemented as follows: + +@example +@group +void Shm_Lock( + Shm_Locked_queue_Control *lq_cb +) +@{ + disable processor interrupts + set Shm_isrstat to previous interrupt disable level + + while ( TRUE ) @{ + atomically attempt to acquire the lock + if the lock was acquired + return + delay some small period of time + @} +@} +@end group +@end example + +@subsubsection Releasing a Shared Lock + +The @code{Shm_Unlock} routine is responsible for +releasing the lock field and reenabling processor +interrupts. This routines usually is implemented as follows: + +@example +@group +void Shm_Unlock( + Shm_Locked_queue_Control *lq_cb +) +@{ + set the lock to the unlocked value + reenable processor interrupts to their level prior + to the lock being acquired. This value was saved + in the global variable Shm_isrstat +@} +@end group +@end example + +@section Installing the MPCI ISR + +The @code{Shm_setvec} is invoked by the portable portion +of the shared memory to install the interrupt service routine +that is invoked when an incoming message is announced. Some +target boards support an interprocessor interrupt or mailbox +scheme and this is where the ISR for that interrupt would be +installed. + +On an interrupt driven node, this routine would be implemented +as follows: + +@example +@group +void Shm_setvec( void ) +@{ + install the interprocessor communications ISR +@} +@end group +@end example + +On a polled node, this routine would be empty. diff --git a/doc/bsp_howto/support.t b/doc/bsp_howto/support.t index 59f0054d7c..eaede9b1dd 100644 --- a/doc/bsp_howto/support.t +++ b/doc/bsp_howto/support.t @@ -6,7 +6,252 @@ @c $Id$ @c -@chapter Required Support Routines +@chapter Miscellaneous Support Files -XXX FILL ME IN +@section GCC Compiler Specifications File + +The file @code{bsp_specs} defines the start files and libraries +that are always used with this BSP. The format of this file +is admittedly cryptic and this document will make no attempt +to explain it completely. Below is the @code{bsp_specs} +file from the PowerPC psim BSP: + +@example +@group +%rename cpp old_cpp +%rename lib old_lib +%rename endfile old_endfile +%rename startfile old_startfile +%rename link old_link + +*cpp: +%(old_cpp) %@{qrtems: -D__embedded__@} -Asystem(embedded) + +*lib: +%@{!qrtems: %(old_lib)@} %@{qrtems: --start-group \ +%@{!qrtems_debug: -lrtemsall@} %@{qrtems_debug: -lrtemsall_g@} \ +-lc -lgcc --end-group ecrtn%O%s \ +%@{!qnolinkcmds: -T linkcmds%s@}@} + +*startfile: +%@{!qrtems: %(old_startfile)@} %@{qrtems: ecrti%O%s \ +%@{!qrtems_debug: startsim.o%s@} \ +%@{qrtems_debug: startsim_g.o%s@}@} + +*link: +%@{!qrtems: %(old_link)@} %@{qrtems: -Qy -dp -Bstatic \ +-T linkcmds%s -e _start -u __vectors@} +@end group +@end example + +The first section of this file renames the built-in definition of +some specification variables so they can be augmented without +embedded their original definition. The subsequent sections +specify what behavior is expected when the @code{-qrtems} or +@code{-qrtems_debug} option is specified. + +The @code{*cpp} definition specifies that when @code{-qrtems} +is specified, predefine the preprocessor symbol @code{__embedded__}. + +The @code{*lib} section insures that the RTEMS library, BSP specific +linker script, gcc support library, and the EABI specific @code{ecrtn} +file are used. + +The @code{*startfile} section specifies that the BSP specific file +@code{startsim.o} will be used instead of @code{crt0.o}. In addition, +the EABI specific file @code{ecrti.o} will be linked in with the +executable. + +The @code{*link} section specifies the arguments that will be passed to +the linker. + +The format of this file is specific to the GNU Compiler Suite. The +argument used to override and extend the compiler built-in specifications +is relatively new to the toolset. The @code{-specs} option is present +in all @code{egcs} distributions and @code{gcc} distributions starting +with version 2.8.0. + +@section README Files + +Most BSPs provide one or more @code{README} files. Generally, there +is a @code{README} file at the top of the BSP source. This file +describes the board and its hardware configuration, provides vendor +information, local configuration information, information on downloading +code to the board, debugging, etc.. The intent of this +file is to help someone begin to use the BSP faster. + +A @code{README} file in a BSP subdirectory typically explains something +about the contents of that subdirectory in greater detail. For example, +it may list the documentation available for a particular peripheral +controller and how to obtain that documentation. It may also explain some +particularly cryptic part of the software in that directory or provide +rationale on the implementation. + +@section times + +This file contains the results of the RTEMS Timing Test Suite. It is +in a standard format so that results from one BSP can be easily compared +with those of another target board. + +If a BSP supports multiple variants, then there may be multiple @code{times} +files. Usually these are named @code{times.VARIANTn}. + +@section Tools Subdirectory + +Some BSPs provide additional tools that aid in using the target board. +These tools run on the development host and are built as part of building +the BSP. Most common is a script to automate running the RTEMS Test Suites +on the BSP. Examples of this include: + +@itemize @bullet + +@item @code{powerpc/psim} includes scripts to ease use of the simulator + +@item @code{m68k/mvme162} includes a utility to download across the +VMEbus into target memory if the host is a VMEbus board in the same +chasis. + +@item @code{unix/posix} includes scripts to run the tests automatically +on this BSP. + +@end itemize + +@section bsp.h Include File + +The file @code{include/bsp.h} contains prototypes and definitions +specific to this board. Every BSP is required to provide a @code{bsp.h}. +The best approach to writing a @code{bsp.h} is copying an existing one +as a starting point. + +Many @code{bsp.h} files provide prototypes of variables defined +in the linker script (@code{linkcmds}). + +There are a number of fields in this file that are used only by the +RTEMS Test Suites. The following is a list of these: + +@itemize @bullet +@item @code{MAX_LONG_TEST_DURATION} - the longest length of time a +"long running" test should run. + +@item @code{MAX_SHORT_TEST_DURATION} - the longest length of time a +"short running" test should run. + +@item @code{MUST_WAIT_FOR_INTERRUPT} - modifies behavior of @code{tm27}. + +@item @code{Install_tm27_vector} - installs the interrupt service +routine for the Interrupt Benchmark Test (@code{tm27}). + +@item @code{Cause_tm27_intr} - generates the interrupt source +used in the Interrupt Benchmark Test (@code{tm27}). + +@item @code{Clear_tm27_intr} - clears the interrupt source +used in the Interrupt Benchmark Test (@code{tm27}). + +@item @code{Lower_tm27_intr} - lowers the interrupt mask so the +interrupt source used in the Interrupt Benchmark Test (@code{tm27}) +can generate a nested interrupt. + +@end itemize + +@section Calling Overhead File + +The file @code{include/coverhd.h} contains the overhead associated +with invoking each directive. This overhead consists of the execution +time required to package the parameters as well as to execute the "jump to +subroutine" and "return from subroutine" sequence. The intent of this +file is to help separate the calling overhead from the actual execution +time of a directive. This file is only used by the tests in the +RTEMS Timing Test Suite. + +The numbers in this file are obtained by running the "Timer Overhead" +@code{tmoverhd} test. The numbers in this file may be 0 and no +overhead is subtracted from the directive execution times reported by +the Timing Suite. + +@section sbrk() Implementation + +If the BSP wants to dynamically extend the heap used by the +C Library memory allocation routines (i.e. @code{malloc} family), +then this routine must be functional. The following is the +prototype for this routine: + +@example +void * sbrk(size_t increment) +@end example + +The @code{increment} amount is based upon the @code{sbrk_amount} +parameter passed to the @code{RTEMS_Malloc_Initialize} during system +initialization. +See @ref{Initialization Code RTEMS Pretasking Callback} for more +information. + +There is a default implementation which returns an error to indicate +that the heap can not be extended. This implementation can be +found in @code{c/src/lib/libbsp/shared/sbrk.c}. Many of the BSPs +use this shared implementation. In order to use this implementation, +the file @code{Makefile.in} in the BSP's @code{startup} directory +must be modified so that the @code{$VPATH} variable searches +both the @code{startup} directory and the shared directory. The following +illustates the @code{VPATH} setting in the PowerPC psim BSP's +@code{startup/Makefile.in}: + +@example +VPATH = @@srcdir@@:@@srcdir@@/../../../shared +@end example + +This instructs make to look in all of the directories in the @code{VPATH} +for the source files. The directories will be examined in the order +they are specified. + +@section bsp_cleanup() - Cleanup the Hardware + +The @code{bsp_cleanup()} is the last C code invoked. Most of the BSPs +use the same shared version of @code{bsp_cleanup()} that does nothing. +This implementation is located in the following file: + +@example +c/src/lib/libbsp/shared/bspclean.c +@end example + +The @code{bsp_cleanup()} routine can be used to return to a ROM monitor, +insure that interrupt sources are disabled, etc.. This routine is the +last place to insure a clean shutdown of the hardware. + +@section set_vector() - Install an Interrupt Vector + +The @code{set_vector} routine is responsible for installing an interrupt +vector. It invokes the support routines necessary to install an +interrupt handler as either a "raw" or an RTEMS interrupt handler. Raw +handlers bypass the RTEMS interrupt structure and are responsible for +saving and restoring all their own registers. Raw handlers are useful +for handling traps, debug vectors, etc.. + +The @code{set_vector} routine is a central place to perform +interrupt controller manipulation and encapsulate that information. +It is usually implemented as follows: + +@example +@group +rtems_isr_entry set_vector( /* returns old vector */ + rtems_isr_entry handler, /* isr routine */ + rtems_vector_number vector, /* vector number */ + int type /* RTEMS or RAW intr */ +) +@{ + if the type is RAW + install the raw vector + else + use rtems_interrupt_catch to install the vector + + perform any interrupt controller necessary to unmask + the interrupt source + + return the previous handler +@} +@end group +@end example + + +@b{NOTE:} @code{set_vector} is provided by the majority of BSPs but +not all. In particular, the i386 BSPs use a different scheme. diff --git a/doc/bsp_howto/timer.t b/doc/bsp_howto/timer.t index d2d5629682..8794ea00ee 100644 --- a/doc/bsp_howto/timer.t +++ b/doc/bsp_howto/timer.t @@ -8,67 +8,114 @@ @chapter Timer Driver -You can program the timer driver for your own needs, but here are two uses -of it: +The timer driver is primarily used by the RTEMS Timing Tests. +This driver provides as accurate a benchmark timer as possible. +It typically reports its time in microseconds, CPU cycles, or +bus cycles. This information can be very useful for determining +precisely what pieces of code require optimization and to measure the +impact of specific minor changes. -@section UART'S FIFO Full Mode +The gen68340 BSP also uses the TImer Driver to support a high performance +mode of the on-CPU UART. -The gen68340 BSP is an example of the use of the timer to support the UART -input FIFO full mode (FIFO means First In First Out and roughly means -buffer). This mode consists in the UART raising an interrupt when n -characters have been received (n is the UA RT's FIFO length). It results -in a lower interrupt processing time, but the problem is that a scanf -primitive will block on a receipt of less than n characters. The solution -is to set a timer that will check whether there are some characters -waiting in th e UART's input FIFO. The delay time has to be set carefully -otherwise high rates will be broken: +@section Benchmark Timer -@itemize @bullet +The RTEMS Timing Test Suite requires a benchmark timer. The +RTEMS Timing Test Suite is very helpful for determining +the performance of target hardware and comparing its performance +to that of other RTEMS targets. -@item if no character was received last time the interrupt subroutine was -entered, set a long delay, +This section describes the routines which are assumed to exist by +the RTEMS Timing Test Suite. The names used are @b{EXACTLY} what +is used in the RTEMS Timing Test Suite so follow the naming convention. -@item otherwise set the delay to the delay needed for n characters -receipt. +@subsection Timer_initialize -@end itemize +Initialize the timer source. -@section Measuring RTEMS Primitives Time +@example +void Timer_initialize(void) +@{ + initialize the benchmark timer +@} +@end example -RTEMS Timing Test Suite needs a timer support. You have to provide two -primitives: +@subsection Read_timer +The @code{Read_timer} routine +returns the number of benchmark time units (typically microseconds) +that have elapsed since the last call to @code{Timer_initialize}. +@example +int Read_timer(void) +@{ + stop time = read the hardware timer + if the subtract overhead feature is enabled + subtract overhead from stop time + return the stop time +@} +@end example -Function +Many implementations of this routine subtract the overhead required +to initialize and read the benchmark timer. This makes the times reported +more accurate. -Description +Some implementations report 0 if the harware timer value change is +sufficiently small. This is intended to indicate that the execution time +is below the resolution of the timer. + +@subsection An Empty Function + +This routine is invoked by the RTEMS Timing Test Suite to measure +the cost of invoking a subroutine. @example -void Timer_initialize (void) +rtems_status_code Empty_function (void) +@{ + return RTEMS_SUCCESSFUL; +@} @end example -Initialize the timer to be a counter to the microsecond. +@subsection Set_find_average_overhead + +This routine is invoked by the "Check Timer" (@code{tmck}) test in the +RTEMS Timing Test Suite. It makes the @code{Read_timer} +routine NOT subtract the overhead required +to initialize and read the benchmark timer. This is used +by the @code{tmoverhd} test to determine the overhead +required to initialize and read the timer. @example -int Read_timer (void) +void Set_find_average_overhead(rtems_boolean find_flag) +@{ + disable the subtract overhead feature +@} @end example -Returns the number of microseconds elapsed since the last call to -Timer_initialize. +The @code{Timer_driver_Find_average_overhead} variable is usually +used to indicate the state of the "subtract overhead feature". -@example -rtems_status_code Empty_function (void) +@section gen68340 UART FIFO Full Mode -return RTEMS_SUCCESSFUL; -@end example +The gen68340 BSP is an example of the use of the timer to support the UART +input FIFO full mode (FIFO means First In First Out and roughly means +buffer). This mode consists in the UART raising an interrupt when n +characters have been received (@i{n} is the UART's FIFO length). It results +in a lower interrupt processing time, but the problem is that a scanf +primitive will block on a receipt of less than @i{n} characters. The solution +is to set a timer that will check whether there are some characters +waiting in the UART's input FIFO. The delay time has to be set carefully +otherwise high rates will be broken: -@example -void Set_find_average_overhead (rtems_boolean find_flag) -@end example +@itemize @bullet -DOES NOTHING ?????????? +@item if no character was received last time the interrupt subroutine was +entered, set a long delay, + +@item otherwise set the delay to the delay needed for @i{n} characters +receipt. + +@end itemize - diff --git a/doc/networking/driver.t b/doc/networking/driver.t index 5de7b54991..e7e5c4335b 100644 --- a/doc/networking/driver.t +++ b/doc/networking/driver.t @@ -8,7 +8,7 @@ @c $Id$ @c -@chapter Writing RTEMS Network Device Drivers +@chapter Networking Driver @section Introduction diff --git a/doc/new_chapters/Makefile b/doc/new_chapters/Makefile index 90d078621d..b84f9ea840 100644 --- a/doc/new_chapters/Makefile +++ b/doc/new_chapters/Makefile @@ -23,7 +23,8 @@ GENERATED_FILES= \ cspecific.texi device.texi dumpcontrol.texi eventlog.texi files.texi \ io.texi key.texi memorymgmt.texi message.texi mutex.texi procenv.texi \ process.texi sched.texi semaphores.texi signal.texi systemdb.texi \ - thread.texi + thread.texi \ + stackchk.texi rtmonuse.texi cpuuse.texi error.texi monitor.texi FILES= posix_users.texi preface.texi \ $(COMMON_FILES) $(GENERATED_FILES) @@ -54,7 +55,6 @@ html: dirs $(FILES) $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \ posix_users.texi - clean: rm -f *.o $(PROG) *.txt core *.html rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE) @@ -170,3 +170,27 @@ systemdb.texi: systemdb.t Makefile -u "Top" \ -n "" ${*}.t +stackchk.texi: stackchk.t Makefile + $(BMENU) -p "" \ + -u "Top" \ + -n "" ${*}.t + +rtmonuse.texi: rtmonuse.t Makefile + $(BMENU) -p "" \ + -u "Top" \ + -n "" ${*}.t + +cpuuse.texi: cpuuse.t Makefile + $(BMENU) -p "" \ + -u "Top" \ + -n "" ${*}.t + +error.texi: error.t Makefile + $(BMENU) -p "" \ + -u "Top" \ + -n "" ${*}.t + +monitor.texi: monitor.t Makefile + $(BMENU) -p "" \ + -u "Top" \ + -n "" ${*}.t diff --git a/doc/new_chapters/files.t b/doc/new_chapters/files.t index 121c70c6c1..1a116cc3fa 100644 --- a/doc/new_chapters/files.t +++ b/doc/new_chapters/files.t @@ -28,6 +28,8 @@ The directives provided by the files and directories manager are: @item @code{creat} - Create a new file or rewrite an existing one @item @code{umask} - Sets a file creation mask @item @code{link} - Creates a link to a file +@item @code{symlink} - Creates a symbolic link to a file +@item @code{readlink} - Obtain the name of the link destination @item @code{mkdir} - Makes a directory @item @code{mkfifo} - Makes a FIFO special file @item @code{unlink} - Removes a directory entry @@ -740,6 +742,133 @@ The caller may (or may not) need permission to access the existing file. NONE +@page +@subsection symlink - Creates a symbolic link to a file + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include + +int symlink( + const char *topath, + const char *frompath +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b + +@item EACCES +Search permission is denied for a directory in a file's path prefix + +@item EEXIST +The named file already exists. + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in +effect. + +@item ENOENT +A file or directory does not exist. + +@item ENOSPC +No space left on disk. + +@item ENOTDIR +A component of the specified pathname was not a directory when a directory +was expected. + +@item EPERM +Operation is not permitted. Process does not have the appropriate priviledges +or permissions to perform the requested operations. + +@item EROFS +Read-only file system. + +@end table + +@subheading DESCRIPTION: + +The @code{symlink()} function creates a symbolic link from the frombath to the +topath. The symbolic link will be interpreted at run-time. + +If the @code{symlink()} function fails, no directories are modified. + +The caller may (or may not) need permission to access the existing file. + +@subheading NOTES: + +NONE + +@page +@subsection readlink - Obtain the name of a symbolic link destination + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include + +int readlink( + const char *path, + char *buf, + size_t bufsize +); + +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b + +@item EACCES +Search permission is denied for a directory in a file's path prefix + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in +effect. + +@item ENOENT +A file or directory does not exist. + +@item ENOTDIR +A component of the prefix pathname was not a directory when a directory +was expected. + +@item ELOOP +Too many symbolic links were encountered in the pathname. + +@item EINVAL +The pathname does not refer to a symbolic link + +@item EFAULT +An invalid pointer was passed into the @code{readlink()} routine. + +@end table + +@subheading DESCRIPTION: + +The @code{readlink()} function places the symbolic link destination into +@code{buf} argument and returns the number of characters copied. + +If the symbolic link destination is longer than bufsize characters the +name will be truncated. + +@subheading NOTES: + +NONE + @page @subsection mkdir - Makes a directory diff --git a/doc/new_chapters/gen_section b/doc/new_chapters/gen_section index d3b8bde58f..d07769455a 100644 --- a/doc/new_chapters/gen_section +++ b/doc/new_chapters/gen_section @@ -129,6 +129,32 @@ case ${chapter} in ROUTINES="strcpy strncpy strcat strncat strcmp strncmp strchr strcspn \ strpbrk strrchr strspn strstr strtok stlen" ;; + misc_stackchk) + CHAPTER_CAPS="Stack Bounds Checker" + CHAPTER_LOWER="stack bounds checker" + ROUTINES="Stack_check_Initialize Stack_check_Dump_usage" + ;; + misc_rtmonuse) + CHAPTER_CAPS="Rate Monotonic Period Statistics" + CHAPTER_LOWER="rate monotonic period statistics" + ROUTINES="Period_usage_Initialize Period_usage_Reset \ + Period_usage_Update Period_usage_Dump" + ;; + misc_cpuuse) + CHAPTER_CAPS="CPU Usage Statistics" + CHAPTER_LOWER="CPU usage statistics" + ROUTINES="CPU_usage_Dump CPU_usage_Reset" + ;; + misc_error) + CHAPTER_CAPS="Error Reporting Support" + CHAPTER_LOWER="error reporting support" + ROUTINES="rtems_error rtems_panic" + ;; + misc_monitor) + CHAPTER_CAPS="Monitor Task" + CHAPTER_LOWER="monitor task" + ROUTINES="rtems_monitor_init rtems_monitor_wakeup" + ;; *) echo "Unknown chapter name" exit 1 diff --git a/doc/new_chapters/posix_users.texi b/doc/new_chapters/posix_users.texi index 3fe66ed75c..36627225ae 100644 --- a/doc/new_chapters/posix_users.texi +++ b/doc/new_chapters/posix_users.texi @@ -107,6 +107,11 @@ END-INFO-DIR-ENTRY @include dumpcontrol.texi @include confspace.texi @include adminiface.texi +@include stackchk.texi +@include rtmonuse.texi +@include cpuuse.texi +@include error.texi +@include monitor.texi @ifinfo @node Top, Preface, (dir), (dir) @top posix_users_new @@ -137,6 +142,11 @@ This is the online version of the RTEMS POSIX API User's Guide * Process Dump Control Manager:: * Configuration Space Manager:: * Administration Interface Manager:: +* Stack Bounds Checker:: +* Rate Monotonic Period Statistics:: +* CPU Usage Statistics:: +* Error Reporting Support:: +* Monitor Task:: * Command and Variable Index:: * Concept Index:: @end menu diff --git a/doc/new_chapters/signal.t b/doc/new_chapters/signal.t index 38e096c403..f37708bd4a 100644 --- a/doc/new_chapters/signal.t +++ b/doc/new_chapters/signal.t @@ -108,6 +108,8 @@ This function adds the @code{signo} to the specified signal @code{set}. @subheading NOTES: +NONE + @page @subsection sigdelset - Delete a Signal from a Signal Set diff --git a/doc/posix1003.1/Makefile b/doc/posix1003.1/Makefile index 3337910981..ca16406029 100644 --- a/doc/posix1003.1/Makefile +++ b/doc/posix1003.1/Makefile @@ -45,7 +45,7 @@ $(PROJECT).ps: $(PROJECT).dvi # run texi2dvi twice to generate the xref's properly. $(PROJECT).dvi: $(FILES) $(TEXI2DVI) -v $(PROJECT).texi - texi2dvi $(PROJECT).texi + texi2dvi -v $(PROJECT).texi ch01.texi: ch01.t $(BMENU) -c -p "Preface" \ diff --git a/doc/posix1003.1/ch06.t b/doc/posix1003.1/ch06.t index 7f1fa9f501..5861886a8e 100644 --- a/doc/posix1003.1/ch06.t +++ b/doc/posix1003.1/ch06.t @@ -22,7 +22,7 @@ pipe(), Function, Dummy Implementation @example dup(), Function, Implemented -dup2(), Function, Untested Implementation +dup2(), Function, Untested Iimplementation @end example @section File Descriptor Deassignment diff --git a/doc/posix1003.1/ch14.t b/doc/posix1003.1/ch14.t index 94ff3daebc..25de89cbf9 100644 --- a/doc/posix1003.1/ch14.t +++ b/doc/posix1003.1/ch14.t @@ -46,21 +46,21 @@ clock_getres(), Function, Implemented @subsection Create a Per-Process Timer @example -timer_create(), Function, Implemented +timer_create(), Function, Dummy Implementation @end example @subsection Delete a Per-Process Timer @example -timer_delete(), Function, Implemented +timer_delete(), Function, Dummy Implementation @end example @subsection Per-Process Timers @example -timer_settime(), Function, Implemented -timer_gettime(), Function, Implemented -timer_getoverrun(), Function, Implemented +timer_settime(), Function, Dummy Implementation +timer_gettime(), Function, Dummy Implementation +timer_getoverrun(), Function, Dummy Implementation @end example @subsection High Resolution Sleep diff --git a/doc/started/Makefile b/doc/started/Makefile index f5f2edf4d6..4366f06d4a 100644 --- a/doc/started/Makefile +++ b/doc/started/Makefile @@ -41,8 +41,8 @@ $(PROJECT).ps: $(PROJECT).dvi # run texi2dvi twice to generate the xref's properly. $(PROJECT).dvi: $(FILES) - $(TEXI2DVI) $(PROJECT).texi - texi2dvi $(PROJECT).texi + $(TEXI2DVI) -v $(PROJECT).texi + texi2dvi -v $(PROJECT).texi intro.texi: intro.t versions.texi $(BMENU) -c -p "Top" \ diff --git a/doc/supplements/hppa1_1/cputable.t b/doc/supplements/hppa1_1/cputable.t index 940510ce86..3758fb61a6 100644 --- a/doc/supplements/hppa1_1/cputable.t +++ b/doc/supplements/hppa1_1/cputable.t @@ -47,26 +47,24 @@ typedef struct @{ @table @code @item pretasking_hook -is the address of the -user provided routine which is invoked once RTEMS initialization -is complete but before interrupts and tasking are enabled. This -field may be NULL to indicate that the hook is not utilized. +is the address of the user provided routine which is invoked +once RTEMS APIs are initialized. This routine will be invoked +before any system tasks are created. Interrupts are disabled. +This field may be NULL to indicate that the hook is not utilized. @item predriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately before -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -but no device drivers are initialized. This field may be NULL to -indicate that the hook is not utilized. +routine that is invoked immediately before the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item postdriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately after -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -and the device drivers are initialized. This field may be NULL -to indicate that the hook is not utilized. +routine that is invoked immediately after the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item idle_task is the address of the optional user diff --git a/doc/supplements/i386/cputable.t b/doc/supplements/i386/cputable.t index 9da005f732..621f99c8c9 100644 --- a/doc/supplements/i386/cputable.t +++ b/doc/supplements/i386/cputable.t @@ -46,26 +46,24 @@ typedef struct @{ @table @code @item pretasking_hook -is the address of the -user provided routine which is invoked once RTEMS initialization -is complete but before interrupts and tasking are enabled. This -field may be NULL to indicate that the hook is not utilized. +is the address of the user provided routine which is invoked +once RTEMS APIs are initialized. This routine will be invoked +before any system tasks are created. Interrupts are disabled. +This field may be NULL to indicate that the hook is not utilized. @item predriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately before -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -but no device drivers are initialized. This field may be NULL to -indicate that the hook is not utilized. +routine that is invoked immediately before the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item postdriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately after -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -and the device drivers are initialized. This field may be NULL -to indicate that the hook is not utilized. +routine that is invoked immediately after the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item idle_task is the address of the optional user diff --git a/doc/supplements/i960/cputable.t b/doc/supplements/i960/cputable.t index e7833eb18b..3baa8e47ef 100644 --- a/doc/supplements/i960/cputable.t +++ b/doc/supplements/i960/cputable.t @@ -54,26 +54,24 @@ by including the file rtems.h. @table @code @item pretasking_hook -is the address of the -user provided routine which is invoked once RTEMS initialization -is complete but before interrupts and tasking are enabled. This -field may be NULL to indicate that the hook is not utilized. +is the address of the user provided routine which is invoked +once RTEMS APIs are initialized. This routine will be invoked +before any system tasks are created. Interrupts are disabled. +This field may be NULL to indicate that the hook is not utilized. @item predriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately before -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -but no device drivers are initialized. This field may be NULL to -indicate that the hook is not utilized. +routine that is invoked immediately before the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item postdriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately after -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -and the device drivers are initialized. This field may be NULL -to indicate that the hook is not utilized. +routine that is invoked immediately after the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item idle_task is the address of the optional user diff --git a/doc/supplements/m68k/cputable.t b/doc/supplements/m68k/cputable.t index 7a7273ea8e..1e16ac7d63 100644 --- a/doc/supplements/m68k/cputable.t +++ b/doc/supplements/m68k/cputable.t @@ -47,26 +47,24 @@ typedef struct @{ @table @code @item pretasking_hook -is the address of the -user provided routine which is invoked once RTEMS initialization -is complete but before interrupts and tasking are enabled. This -field may be NULL to indicate that the hook is not utilized. +is the address of the user provided routine which is invoked +once RTEMS APIs are initialized. This routine will be invoked +before any system tasks are created. Interrupts are disabled. +This field may be NULL to indicate that the hook is not utilized. @item predriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately before -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -but no device drivers are initialized. This field may be NULL to -indicate that the hook is not utilized. +routine that is invoked immediately before the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item postdriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately after -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -and the device drivers are initialized. This field may be NULL -to indicate that the hook is not utilized. +routine that is invoked immediately after the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item idle_task is the address of the optional user diff --git a/doc/supplements/powerpc/cputable.t b/doc/supplements/powerpc/cputable.t index 35fabdb6f3..73bd11a29b 100644 --- a/doc/supplements/powerpc/cputable.t +++ b/doc/supplements/powerpc/cputable.t @@ -54,26 +54,24 @@ typedef struct @{ @table @code @item pretasking_hook -is the address of the -user provided routine which is invoked once RTEMS initialization -is complete but before interrupts and tasking are enabled. This -field may be NULL to indicate that the hook is not utilized. +is the address of the user provided routine which is invoked +once RTEMS APIs are initialized. This routine will be invoked +before any system tasks are created. Interrupts are disabled. +This field may be NULL to indicate that the hook is not utilized. @item predriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately before -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -but no device drivers are initialized. This field may be NULL to -indicate that the hook is not utilized. +routine that is invoked immediately before the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item postdriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately after -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -and the device drivers are initialized. This field may be NULL -to indicate that the hook is not utilized. +routine that is invoked immediately after the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item idle_task is the address of the optional user diff --git a/doc/supplements/sparc/cputable.t b/doc/supplements/sparc/cputable.t index 4e37375c9c..64114f956e 100644 --- a/doc/supplements/sparc/cputable.t +++ b/doc/supplements/sparc/cputable.t @@ -43,26 +43,24 @@ typedef struct @{ @table @code @item pretasking_hook -is the address of the -user provided routine which is invoked once RTEMS initialization -is complete but before interrupts and tasking are enabled. This -field may be NULL to indicate that the hook is not utilized. +is the address of the user provided routine which is invoked +once RTEMS APIs are initialized. This routine will be invoked +before any system tasks are created. Interrupts are disabled. +This field may be NULL to indicate that the hook is not utilized. @item predriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately before -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -but no device drivers are initialized. This field may be NULL to -indicate that the hook is not utilized. +routine that is invoked immediately before the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item postdriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately after -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -and the device drivers are initialized. This field may be NULL -to indicate that the hook is not utilized. +routine that is invoked immediately after the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item idle_task is the address of the optional user diff --git a/doc/supplements/template/cputable.t b/doc/supplements/template/cputable.t index a2164335aa..8018c4c8d3 100644 --- a/doc/supplements/template/cputable.t +++ b/doc/supplements/template/cputable.t @@ -47,26 +47,24 @@ typedef struct @{ @table @code @item pretasking_hook -is the address of the -user provided routine which is invoked once RTEMS initialization -is complete but before interrupts and tasking are enabled. This -field may be NULL to indicate that the hook is not utilized. +is the address of the user provided routine which is invoked +once RTEMS APIs are initialized. This routine will be invoked +before any system tasks are created. Interrupts are disabled. +This field may be NULL to indicate that the hook is not utilized. @item predriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately before -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -but no device drivers are initialized. This field may be NULL to -indicate that the hook is not utilized. +routine that is invoked immediately before the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item postdriver_hook is the address of the user provided -routine which is invoked with tasking enabled immediately after -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -and the device drivers are initialized. This field may be NULL -to indicate that the hook is not utilized. +routine that is invoked immediately after the +the device drivers and MPCI are initialized. RTEMS +initialization is complete but interrupts and tasking are disabled. +This field may be NULL to indicate that the hook is not utilized. @item idle_task is the address of the optional user -- cgit v1.2.3