Clean up the CPU Supplement.

1 files changed, 172 insertions, 190 deletions

diff --git a/cpu_supplement/m68xxx_and_coldfire.rst b/cpu_supplement/m68xxx_and_coldfire.rst
index 0383847..d448276 100644
--- a/cpu_supplement/m68xxx_and_coldfire.rst
+++ b/cpu_supplement/m68xxx_and_coldfire.rst
@@ -1,21 +1,24 @@
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
 
+.. COMMENT: Copyright (c) 2014 embedded brains GmbH.  All rights reserved.
+
 M68xxx and Coldfire Specific Information
 ########################################
 
-This chapter discusses the Freescale (formerly Motorola) MC68xxx
-and Coldfire architectural dependencies.  The MC68xxx family has a
-wide variety of CPU models within it based upon different CPU core
-implementations.  Ignoring the Coldfire parts, the part numbers for
-these models are generally divided into MC680xx and MC683xx.  The MC680xx
-models are more general purpose processors with no integrated peripherals.
-The MC683xx models, on the other hand, are more specialized and have a
-variety of peripherals on chip including sophisticated timers and serial
-communications controllers.
+This chapter discusses the Freescale (formerly Motorola) MC68xxx and Coldfire
+architectural dependencies.  The MC68xxx family has a wide variety of CPU
+models within it based upon different CPU core implementations.  Ignoring the
+Coldfire parts, the part numbers for these models are generally divided into
+MC680xx and MC683xx.  The MC680xx models are more general purpose processors
+with no integrated peripherals.  The MC683xx models, on the other hand, are
+more specialized and have a variety of peripherals on chip including
+sophisticated timers and serial communications controllers.
 
 **Architecture Documents**
 
-For information on the MC68xxx and Coldfire architecture, refer to the following documents available from Freescale website (:file:`http//www.freescale.com/`):
+For information on the MC68xxx and Coldfire architecture, refer to the
+following documents available from Freescale website
+(http//www.freescale.com/):
 
 - *M68000 Family Reference, Motorola, FR68K/D*.
 
@@ -27,82 +30,81 @@ For information on the MC68xxx and Coldfire architecture, refer to the following
 CPU Model Dependent Features
 ============================
 
-This section presents the set of features which vary
-across m68k/Coldfire implementations that are of importance to RTEMS.
-The set of CPU model feature macros are defined in the file``cpukit/score/cpu/m68k/m68k.h`` based upon the particular CPU
-model selected on the compilation command line.
+This section presents the set of features which vary across m68k/Coldfire
+implementations that are of importance to RTEMS.  The set of CPU model feature
+macros are defined in the file :file:`cpukit/score/cpu/m68k/m68k.h` based upon
+the particular CPU model selected on the compilation command line.
 
 BFFFO Instruction
 -----------------
 
-The macro ``M68K_HAS_BFFFO`` is set to 1 to indicate that
-this CPU model has the bfffo instruction.
+The macro ``M68K_HAS_BFFFO`` is set to 1 to indicate that this CPU model has
+the bfffo instruction.
 
 Vector Base Register
 --------------------
 
-The macro ``M68K_HAS_VBR`` is set to 1 to indicate that
-this CPU model has a vector base register (vbr).
+The macro ``M68K_HAS_VBR`` is set to 1 to indicate that this CPU model has a
+vector base register (vbr).
 
 Separate Stacks
 ---------------
 
-The macro ``M68K_HAS_SEPARATE_STACKS`` is set to 1 to
-indicate that this CPU model has separate interrupt, user, and
-supervisor mode stacks.
+The macro ``M68K_HAS_SEPARATE_STACKS`` is set to 1 to indicate that this CPU
+model has separate interrupt, user, and supervisor mode stacks.
 
 Pre-Indexing Address Mode
 -------------------------
 
-The macro ``M68K_HAS_PREINDEXING`` is set to 1 to indicate that
-this CPU model has the pre-indexing address mode.
+The macro ``M68K_HAS_PREINDEXING`` is set to 1 to indicate that this CPU model
+has the pre-indexing address mode.
 
 Extend Byte to Long Instruction
 -------------------------------
 
-The macro ``M68K_HAS_EXTB_L`` is set to 1 to indicate that this CPU model
-has the extb.l instruction.  This instruction is supposed to be available
-in all models based on the cpu32 core as well as mc68020 and up models.
+The macro ``M68K_HAS_EXTB_L`` is set to 1 to indicate that this CPU model has
+the extb.l instruction.  This instruction is supposed to be available in all
+models based on the cpu32 core as well as mc68020 and up models.
 
 Calling Conventions
 ===================
 
-The MC68xxx architecture supports a simple yet effective call and
-return mechanism.  A subroutine is invoked via the branch to subroutine
-(``bsr``) or the jump to subroutine (``jsr``) instructions.
-These instructions push the return address on the current stack.
-The return from subroutine (``rts``) instruction pops the return
-address off the current stack and transfers control to that instruction.
-It is is important to note that the MC68xxx call and return mechanism does
-not automatically save or restore any registers.  It is the responsibility
-of the high-level language compiler to define the register preservation
-and usage convention.
+The MC68xxx architecture supports a simple yet effective call and return
+mechanism.  A subroutine is invoked via the branch to subroutine (``bsr``) or
+the jump to subroutine (``jsr``) instructions.  These instructions push the
+return address on the current stack.  The return from subroutine (``rts``)
+instruction pops the return address off the current stack and transfers control
+to that instruction.  It is is important to note that the MC68xxx call and
+return mechanism does not automatically save or restore any registers.  It is
+the responsibility of the high-level language compiler to define the register
+preservation and usage convention.
 
 Calling Mechanism
 -----------------
 
-All RTEMS directives are invoked using either a ``bsr`` or ``jsr``
-instruction and return to the user application via the rts instruction.
+All RTEMS directives are invoked using either a ``bsr`` or ``jsr`` instruction
+and return to the user application via the rts instruction.
 
 Register Usage
 --------------
 
-As discussed above, the ``bsr`` and ``jsr`` instructions do not
-automatically save any registers.  RTEMS uses the registers D0, D1,
-A0, and A1 as scratch registers.  These registers are not preserved by
-RTEMS directives therefore, the contents of these registers should not
-be assumed upon return from any RTEMS directive.
+As discussed above, the ``bsr`` and ``jsr`` instructions do not automatically
+save any registers.  RTEMS uses the registers D0, D1, A0, and A1 as scratch
+registers.  These registers are not preserved by RTEMS directives therefore,
+the contents of these registers should not be assumed upon return from any
+RTEMS directive.
 
 Parameter Passing
 -----------------
 
-RTEMS assumes that arguments are placed on the current stack before
-the directive is invoked via the bsr or jsr instruction.  The first
-argument is assumed to be closest to the return address on the stack.
-This means that the first argument of the C calling sequence is pushed
-last.  The following pseudo-code illustrates the typical sequence used
-to call a RTEMS directive with three (3) arguments:
-.. code:: c
+RTEMS assumes that arguments are placed on the current stack before the
+directive is invoked via the bsr or jsr instruction.  The first argument is
+assumed to be closest to the return address on the stack.  This means that the
+first argument of the C calling sequence is pushed last.  The following
+pseudo-code illustrates the typical sequence used to call a RTEMS directive
+with three (3) arguments:
+
+.. code-block:: c
 
     push third argument
     push second argument
@@ -111,93 +113,84 @@ to call a RTEMS directive with three (3) arguments:
     remove arguments from the stack
 
 The arguments to RTEMS are typically pushed onto the stack using a move
-instruction with a pre-decremented stack pointer as the destination.
-These arguments must be removed from the stack after control is returned
-to the caller.  This removal is typically accomplished by adding the
-size of the argument list in bytes to the current stack pointer.
+instruction with a pre-decremented stack pointer as the destination.  These
+arguments must be removed from the stack after control is returned to the
+caller.  This removal is typically accomplished by adding the size of the
+argument list in bytes to the current stack pointer.
 
 Memory Model
 ============
 
-The MC68xxx family supports a flat 32-bit address
-space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
-gigabytes).  Each address is represented by a 32-bit value and
-is byte addressable.  The address may be used to reference a
-single byte, word (2-bytes), or long word (4 bytes).  Memory
-accesses within this address space are performed in big endian
-fashion by the processors in this family.
-
-Some of the MC68xxx family members such as the
-MC68020, MC68030, and MC68040 support virtual memory and
-segmentation.  The MC68020 requires external hardware support
-such as the MC68851 Paged Memory Management Unit coprocessor
-which is typically used to perform address translations for
-these systems.  RTEMS does not support virtual memory or
-segmentation on any of the MC68xxx family members.
+The MC68xxx family supports a flat 32-bit address space with addresses ranging
+from 0x00000000 to 0xFFFFFFFF (4 gigabytes).  Each address is represented by a
+32-bit value and is byte addressable.  The address may be used to reference a
+single byte, word (2-bytes), or long word (4 bytes).  Memory accesses within
+this address space are performed in big endian fashion by the processors in
+this family.
+
+Some of the MC68xxx family members such as the MC68020, MC68030, and MC68040
+support virtual memory and segmentation.  The MC68020 requires external
+hardware support such as the MC68851 Paged Memory Management Unit coprocessor
+which is typically used to perform address translations for these systems.
+RTEMS does not support virtual memory or segmentation on any of the MC68xxx
+family members.
 
 Interrupt Processing
 ====================
 
-Discussed in this section are the MC68xxx's interrupt response and
-control mechanisms as they pertain to RTEMS.
+Discussed in this section are the MC68xxx's interrupt response and control
+mechanisms as they pertain to RTEMS.
 
 Vectoring of an Interrupt Handler
 ---------------------------------
 
-Depending on whether or not the particular CPU supports a separate
-interrupt stack, the MC68xxx family has two different interrupt handling
-models.
+Depending on whether or not the particular CPU supports a separate interrupt
+stack, the MC68xxx family has two different interrupt handling models.
 
 Models Without Separate Interrupt Stacks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Upon receipt of an interrupt the MC68xxx family members without separate
-interrupt stacks automatically perform the following actions:
-
-- To Be Written
+interrupt stacks automatically use software to switch stacks.
 
 Models With Separate Interrupt Stacks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Upon receipt of an interrupt the MC68xxx family members with separate
-interrupt stacks automatically perform the following actions:
+Upon receipt of an interrupt the MC68xxx family members with separate interrupt
+stacks automatically perform the following actions:
 
 - saves the current status register (SR),
 
-- clears the master/interrupt (M) bit of the SR to
-  indicate the switch from master state to interrupt state,
+- clears the master/interrupt (M) bit of the SR to indicate the switch from
+  master state to interrupt state,
 
 - sets the privilege mode to supervisor,
 
 - suppresses tracing,
 
-- sets the interrupt mask level equal to the level of the
-  interrupt being serviced,
+- sets the interrupt mask level equal to the level of the interrupt being
+  serviced,
 
-- pushes an interrupt stack frame (ISF), which includes
-  the program counter (PC), the status register (SR), and the
-  format/exception vector offset (FVO) word, onto the supervisor
-  and interrupt stacks,
+- pushes an interrupt stack frame (ISF), which includes the program counter
+  (PC), the status register (SR), and the format/exception vector offset (FVO)
+  word, onto the supervisor and interrupt stacks,
 
-- switches the current stack to the interrupt stack and
-  vectors to an interrupt service routine (ISR).  If the ISR was
-  installed with the interrupt_catch directive, then the RTEMS
-  interrupt handler will begin execution.  The RTEMS interrupt
-  handler saves all registers which are not preserved according to
+- switches the current stack to the interrupt stack and vectors to an interrupt
+  service routine (ISR).  If the ISR was installed with the interrupt_catch
+  directive, then the RTEMS interrupt handler will begin execution.  The RTEMS
+  interrupt handler saves all registers which are not preserved according to
   the calling conventions and invokes the application's ISR.
 
-A nested interrupt is processed similarly by these
-CPU models with the exception that only a single ISF is placed
-on the interrupt stack and the current stack need not be
-switched.
+A nested interrupt is processed similarly by these CPU models with the
+exception that only a single ISF is placed on the interrupt stack and the
+current stack need not be switched.
 
-The FVO word in the Interrupt Stack Frame is examined
-by RTEMS to determine when an outer most interrupt is being
-exited. Since the FVO is used by RTEMS for this purpose, the
-user application code MUST NOT modify this field.
+The FVO word in the Interrupt Stack Frame is examined by RTEMS to determine
+when an outer most interrupt is being exited. Since the FVO is used by RTEMS
+for this purpose, the user application code MUST NOT modify this field.
 
-The following shows the Interrupt Stack Frame for
-MC68xxx CPU models with separate interrupt stacks:
+The following shows the Interrupt Stack Frame for MC68xxx CPU models with
+separate interrupt stacks:
 
 +----------------------+-----+
 |    Status Register   | 0x0 |
@@ -213,22 +206,22 @@ MC68xxx CPU models with separate interrupt stacks:
 CPU Models Without VBR and RAM at 0
 -----------------------------------
 
-This is from a post by Zoltan Kocsi <zoltan@bendor.com.au> and is
-a nice trick in certain situations.  In his words:
+This is from a post by Zoltan Kocsi <zoltan@bendor.com.au> and is a nice trick
+in certain situations.  In his words:
 
-I think somebody on this list asked about the interupt vector handling
-w/o VBR and RAM at 0.  The usual trick is to initialise the vector table
-(except the first 2 two entries, of course) to point to the same location
-BUT you also add the vector number times 0x1000000 to them. That is,
-bits 31-24 contain the vector number and 23-0 the address of the common
-handler.  Since the PC is 32 bit wide but the actual address bus is only
-24, the top byte will be in the PC but will be ignored when jumping onto
-your routine.
+I think somebody on this list asked about the interupt vector handling w/o VBR
+and RAM at 0.  The usual trick is to initialise the vector table (except the
+first 2 two entries, of course) to point to the same location BUT you also add
+the vector number times 0x1000000 to them. That is, bits 31-24 contain the
+vector number and 23-0 the address of the common handler.  Since the PC is 32
+bit wide but the actual address bus is only 24, the top byte will be in the PC
+but will be ignored when jumping onto your routine.
 
-Then your common interrupt routine gets this info by loading the PC
-into some register and based on that info, you can jump to a vector in
-a vector table pointed by a virtual VBR:
-.. code:: c
+Then your common interrupt routine gets this info by loading the PC into some
+register and based on that info, you can jump to a vector in a vector table
+pointed by a virtual VBR:
+
+.. code-block:: c
 
     //
     //  Real vector table at 0
@@ -247,51 +240,50 @@ a vector table pointed by a virtual VBR:
     // routine will see exactly what it would see if it was called
     // directly from the HW vector table at 0.
     //
-    .comm    VBR,4,2        // This defines the 'virtual' VBR
-    // From C: extern void \*VBR;
+        .comm    VBR,4,2        // This defines the 'virtual' VBR
+    // From C: extern void *VBR;
     myhandler:                  // At entry, PC contains the full vector
-    move.l  %d0,-(%sp)      // Save d0
-    move.l  %a0,-(%sp)      // Save a0
-    lea     0(%pc),%a0      // Get the value of the PC
-    move.l  %a0,%d0         // Copy it to a data reg, d0 is VV??????
-    swap    %d0             // Now d0 is ????VV??
-    and.w   #0xff00,%d0     // Now d0 is ????VV00 (1)
-    lsr.w   #6,%d0          // Now d0.w contains the VBR table offset
-    move.l  VBR,%a0         // Get the address from VBR to a0
-    move.l  (%a0,%d0.w),%a0 // Fetch the vector
-    move.l  4(%sp),%d0      // Restore d0
-    move.l  %a0,4(%sp)      // Place target address to the stack
-    move.l  (%sp)+,%a0      // Restore a0, target address is on TOS
-    ret                     // This will jump to the handler and
+        move.l  %d0,-(%sp)      // Save d0
+        move.l  %a0,-(%sp)      // Save a0
+        lea     0(%pc),%a0      // Get the value of the PC
+        move.l  %a0,%d0         // Copy it to a data reg, d0 is VV??????
+        swap    %d0             // Now d0 is ????VV??
+        and.w   #0xff00,%d0     // Now d0 is ????VV00 (1)
+        lsr.w   #6,%d0          // Now d0.w contains the VBR table offset
+        move.l  VBR,%a0         // Get the address from VBR to a0
+        move.l  (%a0,%d0.w),%a0 // Fetch the vector
+        move.l  4(%sp),%d0      // Restore d0
+        move.l  %a0,4(%sp)      // Place target address to the stack
+        move.l  (%sp)+,%a0      // Restore a0, target address is on TOS
+        ret                     // This will jump to the handler and
     // restore the stack
-    (1) If 'myhandler' is guaranteed to be in the first 64K, e.g. just
+
+(1) If 'myhandler' is guaranteed to be in the first 64K, e.g. just
     after the vector table then that insn is not needed.
 
-There are probably shorter ways to do this, but it I believe is enough
-to illustrate the trick. Optimisation is left as an exercise to the
-reader :-)
+There are probably shorter ways to do this, but it I believe is enough to
+illustrate the trick. Optimisation is left as an exercise to the reader :-)
 
 Interrupt Levels
 ----------------
 
-Eight levels (0-7) of interrupt priorities are
-supported by MC68xxx family members with level seven (7) being
-the highest priority.  Level zero (0) indicates that interrupts
-are fully enabled.  Interrupt requests for interrupts with
-priorities less than or equal to the current interrupt mask
-level are ignored.
+Eight levels (0-7) of interrupt priorities are supported by MC68xxx family
+members with level seven (7) being the highest priority.  Level zero (0)
+indicates that interrupts are fully enabled.  Interrupt requests for interrupts
+with priorities less than or equal to the current interrupt mask level are
+ignored.
 
-Although RTEMS supports 256 interrupt levels, the
-MC68xxx family only supports eight.  RTEMS interrupt levels 0
-through 7 directly correspond to MC68xxx interrupt levels.  All
-other RTEMS interrupt levels are undefined and their behavior is
-unpredictable.
+Although RTEMS supports 256 interrupt levels, the MC68xxx family only supports
+eight.  RTEMS interrupt levels 0 through 7 directly correspond to MC68xxx
+interrupt levels.  All other RTEMS interrupt levels are undefined and their
+behavior is unpredictable.
 
 Default Fatal Error Processing
 ==============================
 
 The default fatal error handler for this architecture disables processor
-interrupts to level 7, places the error code in D0, and executes a``stop`` instruction to simulate a halt processor instruction.
+interrupts to level 7, places the error code in D0, and executes a ``stop``
+instruction to simulate a halt processor instruction.
 
 Symmetric Multiprocessing
 =========================
@@ -310,65 +302,55 @@ System Reset
 ------------
 
 An RTEMS based application is initiated or re-initiated when the MC68020
-processor is reset.  When the MC68020 is reset, the processor performs
-the following actions:
+processor is reset.  When the MC68020 is reset, the processor performs the
+following actions:
 
-- The tracing bits of the status register are cleared to
-  disable tracing.
+- The tracing bits of the status register are cleared to disable tracing.
 
-- The supervisor interrupt state is entered by setting the
-  supervisor (S) bit and clearing the master/interrupt (M) bit of
-  the status register.
+- The supervisor interrupt state is entered by setting the supervisor (S) bit
+  and clearing the master/interrupt (M) bit of the status register.
 
-- The interrupt mask of the status register is set to
-  level 7 to effectively disable all maskable interrupts.
+- The interrupt mask of the status register is set to level 7 to effectively
+  disable all maskable interrupts.
 
 - The vector base register (VBR) is set to zero.
 
-- The cache control register (CACR) is set to zero to
-  disable and freeze the processor cache.
+- The cache control register (CACR) is set to zero to disable and freeze the
+  processor cache.
 
-- The interrupt stack pointer (ISP) is set to the value
-  stored at vector 0 (bytes 0-3) of the exception vector table
-  (EVT).
+- The interrupt stack pointer (ISP) is set to the value stored at vector 0
+  (bytes 0-3) of the exception vector table (EVT).
 
-- The program counter (PC) is set to the value stored at
-  vector 1 (bytes 4-7) of the EVT.
+- The program counter (PC) is set to the value stored at vector 1 (bytes 4-7)
+  of the EVT.
 
-- The processor begins execution at the address stored in
-  the PC.
+- The processor begins execution at the address stored in the PC.
 
 Processor Initialization
 ------------------------
 
-The address of the application's initialization code should be stored in
-the first vector of the EVT which will allow the immediate vectoring to
-the application code.  If the application requires that the VBR be some
-value besides zero, then it should be set to the required value at this
-point.  All tasks share the same MC68020's VBR value.  Because interrupts
-are enabled automatically by RTEMS as part of the context switch to the
-first task, the VBR MUST be set by either RTEMS of the BSP before this
-occurs ensure correct interrupt vectoring.  If processor caching is
-to be utilized, then it should be enabled during the reset application
-initialization code.
-
-In addition to the requirements described in the
-Board Support Packages chapter of the Applications User's
-Manual for the reset code which is executed before the call to
-initialize executive, the MC68020 version has the following
+The address of the application's initialization code should be stored in the
+first vector of the EVT which will allow the immediate vectoring to the
+application code.  If the application requires that the VBR be some value
+besides zero, then it should be set to the required value at this point.  All
+tasks share the same MC68020's VBR value.  Because interrupts are enabled
+automatically by RTEMS as part of the context switch to the first task, the VBR
+MUST be set by either RTEMS of the BSP before this occurs ensure correct
+interrupt vectoring.  If processor caching is to be utilized, then it should be
+enabled during the reset application initialization code.
+
+In addition to the requirements described in the Board Support Packages chapter
+of the Applications User's Manual for the reset code which is executed before
+the call to initialize executive, the MC68020 version has the following
 specific requirements:
 
-- Must leave the S bit of the status register set so that
-  the MC68020 remains in the supervisor state.
+- Must leave the S bit of the status register set so that the MC68020 remains
+  in the supervisor state.
 
-- Must set the M bit of the status register to remove the
-  MC68020 from the interrupt state.
+- Must set the M bit of the status register to remove the MC68020 from the
+  interrupt state.
 
-- Must set the master stack pointer (MSP) such that a
-  minimum stack size of MINIMUM_STACK_SIZE bytes is provided for
-  the initialize executive directive.
+- Must set the master stack pointer (MSP) such that a minimum stack size of
+  MINIMUM_STACK_SIZE bytes is provided for the initialize executive directive.
 
 - Must initialize the MC68020's vector table.
-
-.. COMMENT: Copyright (c) 2014 embedded brains GmbH.  All rights reserved.
-