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