Update the BSP howto.

Closes #2590.

1 files changed, 56 insertions, 60 deletions

diff --git a/bsp_howto/timer.rst b/bsp_howto/timer.rst
index 9247b2f..9d2bd67 100644
--- a/bsp_howto/timer.rst
+++ b/bsp_howto/timer.rst
@@ -1,106 +1,102 @@
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
 
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Timer Driver
 ############
 
-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.
+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.
 
-The gen68340 BSP also uses the Timer Driver to support a high performance
-mode of the on-CPU UART.
+The gen68340 BSP also uses the Timer Driver to support a high performance mode
+of the on-CPU UART.
 
 Benchmark Timer
 ===============
 
-The RTEMS Timing Test Suite requires a benchmark timer.  The
-RTEMS Timing Test Suite is very helpful for determining
-the performance of target hardware and comparing its performance
-to that of other RTEMS targets.
+The RTEMS Timing Test Suite requires a benchmark timer.  The RTEMS Timing Test
+Suite is very helpful for determining the performance of target hardware and
+comparing its performance to that of other RTEMS targets.
 
-This section describes the routines which are assumed to exist by
-the RTEMS Timing Test Suite.  The names used are *EXACTLY* what
-is used in the RTEMS Timing Test Suite so follow the naming convention.
+This section describes the routines which are assumed to exist by the RTEMS
+Timing Test Suite.  The names used are *EXACTLY* what is used in the RTEMS
+Timing Test Suite so follow the naming convention.
 
 benchmark_timer_initialize
 --------------------------
 
 Initialize the timer source.
-.. code:: c
+
+.. code-block:: c
 
     void benchmark_timer_initialize(void)
     {
-    initialize the benchmark timer
+      initialize the benchmark timer
     }
 
 Read_timer
 ----------
 
-The ``benchmark_timer_read`` routine returns the number of benchmark
-time units (typically microseconds) that have elapsed since the last
-call to ``benchmark_timer_initialize``.
-.. code:: c
+The ``benchmark_timer_read`` routine returns the number of benchmark time units
+(typically microseconds) that have elapsed since the last call to
+``benchmark_timer_initialize``.
+
+.. code-block:: c
 
     benchmark_timer_t benchmark_timer_read(void)
     {
-    stop time = read the hardware timer
-    if the subtract overhead feature is enabled
-    subtract overhead from stop time
-    return the stop time
+      stop time = read the hardware timer
+      if the subtract overhead feature is enabled
+        subtract overhead from stop time
+      return the stop time
     }
 
-Many implementations of this routine subtract the overhead required
-to initialize and read the benchmark timer.  This makes the times reported
-more accurate.
+Many implementations of this routine subtract the overhead required to
+initialize and read the benchmark timer.  This makes the times reported more
+accurate.
 
-Some implementations report 0 if the harware timer value change is
-sufficiently small.  This is intended to indicate that the execution time
-is below the resolution of the timer.
+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.
 
 benchmark_timer_disable_subtracting_average_overhead
 ----------------------------------------------------
 
-This routine is invoked by the "Check Timer" (``tmck``) test in the
-RTEMS Timing Test Suite.  It makes the ``benchmark_timer_read``
-routine NOT subtract the overhead required
-to initialize and read the benchmark timer.  This is used
-by the ``tmoverhd`` test to determine the overhead
-required to initialize and read the timer.
+This routine is invoked by the "Check Timer" (``tmck``) test in the RTEMS
+Timing Test Suite.  It makes the ``benchmark_timer_read`` routine NOT subtract
+the overhead required to initialize and read the benchmark timer.  This is used
+by the ``tmoverhd`` test to determine the overhead required to initialize and
+read the timer.
+
 .. code:: c
 
     void benchmark_timer_disable_subtracting_average_overhead(bool find_flag)
     {
-    disable the subtract overhead feature
+      disable the subtract overhead feature
     }
 
-The ``benchmark_timer_find_average_overhead`` variable is used to
-indicate the state of the "subtract overhead feature".
+The ``benchmark_timer_find_average_overhead`` variable is used to indicate the
+state of the "subtract overhead feature".
 
 gen68340 UART FIFO Full Mode
 ============================
 
 The gen68340 BSP is an example of the use of the timer to support the UART
 input FIFO full mode (FIFO means First In First Out and roughly means
-buffer). This mode consists in the UART raising an interrupt when n
-characters have been received (*n* is the UART's FIFO length). It results
-in a lower interrupt processing time, but the problem is that a scanf
-primitive will block on a receipt of less than *n* characters. The solution
-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:
-
-- if no character was received last time the interrupt subroutine was
-  entered, set a long delay,
-
-- otherwise set the delay to the delay needed for *n* characters
-  receipt.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
+buffer). This mode consists in the UART raising an interrupt when n characters
+have been received (*n* is the UART's FIFO length). It results in a lower
+interrupt processing time, but the problem is that a scanf primitive will block
+on a receipt of less than *n* characters. The solution 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:
+
+- if no character was received last time the interrupt subroutine was entered,
+  set a long delay,
+
+- otherwise set the delay to the delay needed for ``n`` characters receipt.