2008-06-02 Joel Sherrill <joel.sherrill@oarcorp.com>

* cpu_supplement/.cvsignore, cpu_supplement/Makefile.am,
	cpu_supplement/arm.t, cpu_supplement/bfin.t,
	cpu_supplement/cpu_supplement.texi, cpu_supplement/i386.t,
	cpu_supplement/m68k.t, cpu_supplement/mips.t,
	cpu_supplement/powerpc.t, cpu_supplement/preface.texi,
	cpu_supplement/sh.t: Remove duplicated text from each CPU specific
	chapter. This text was necessary when each CPU was a separate manual
	but now only needs to be one place and that is in an introductory
	chapter.
	* cpu_supplement/general.t: New file.

doc/ChangeLog

@@ -1,3 +1,16 @@
+2008-06-02	Joel Sherrill <joel.sherrill@oarcorp.com>
+
+	* cpu_supplement/.cvsignore, cpu_supplement/Makefile.am,
+	cpu_supplement/arm.t, cpu_supplement/bfin.t,
+	cpu_supplement/cpu_supplement.texi, cpu_supplement/i386.t,
+	cpu_supplement/m68k.t, cpu_supplement/mips.t,
+	cpu_supplement/powerpc.t, cpu_supplement/preface.texi,
+	cpu_supplement/sh.t: Remove duplicated text from each CPU specific
+	chapter. This text was necessary when each CPU was a separate manual
+	but now only needs to be one place and that is in an introductory
+	chapter.
+	* cpu_supplement/general.t: New file.
+
 2008-06-02	Joel Sherrill <joel.sherrill@oarcorp.com>
 
 	* user/bsp.t, user/init.t: Rework initialization and BSP chapters to

doc/cpu_supplement/.cvsignore

@@ -21,6 +21,7 @@ cpu_supplement.ps
 cpu_supplement.toc
 cpu_supplement.tp
 cpu_supplement.vr
+general.texi
 i386.texi
 index.html
 m68k.texi

doc/cpu_supplement/Makefile.am

@@ -21,7 +21,7 @@ TEXI2WWW_ARGS=\
 -header rtems_header.html \
 -footer rtems_footer.html \
 -icons ../images
-GENERATED_FILES = arm.texi bfin.texi i386.texi m68k.texi mips.texi \
+GENERATED_FILES = general.texi arm.texi bfin.texi i386.texi m68k.texi mips.texi \
     powerpc.texi sh.texi sparc.texi tic4x.texi
 
 COMMON_FILES += $(top_srcdir)/common/cpright.texi
@@ -35,11 +35,16 @@ cpu_supplement_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)
 #  Chapters which get automatic processing
 #
 
-arm.texi: arm.t
+general.texi: general.t
 	$(BMENU2) -p "Preface" \
 	    -u "Top" \
 	    -n "" < $< > $@
 
+arm.texi: arm.t
+	$(BMENU2) -p "" \
+	    -u "Top" \
+	    -n "" < $< > $@
+
 bfin.texi: bfin.t
 	$(BMENU2) -p "" \
 	    -u "Top" \

doc/cpu_supplement/cpu_supplement.texi

@@ -59,6 +59,7 @@
 @contents
 
 @include preface.texi
+@include general.texi
 @include arm.texi
 @include bfin.texi
 @include i386.texi
@@ -72,14 +73,15 @@
 @node Top, Preface, (dir), (dir)
 @top cpu_supplement
 
-This is the online version of the RTEMS CPU Architecture Supplement
+This is the online version of the RTEMS CPU Architecture Supplement.
 
 @menu
 * Preface::
+* Port Specific Information::
 * ARM Specific Information::
 * Blackfin Specific Information::
 * Intel/AMD x86 Specific Information::
-* Motorola M68xxx and Coldfire Specific Information::
+* M68xxx and Coldfire Specific Information::
 * MIPS Specific Information::
 * PowerPC Specific Information::
 * SuperH Specific Information::

doc/cpu_supplement/preface.texi

@@ -7,7 +7,7 @@
 @c
 
 @ifinfo
-@node Preface, ARM Specific Information, Top, Top
+@node Preface, Port Specific Information, Top, Top
 @end ifinfo
 @unnumbered Preface
 
@@ -21,5 +21,35 @@ issues, interrupt processing, exact RTEMS memory requirements,
 performance data, header files, and the assembly language
 interface to the executive.
 
-Each chapter in this document discusses the details of how
-RTEMS was ported.
+Each architecture represents a CPU family and usually there are
+a wide variety of CPU models within it.  These models share a
+common Instruction Set Architecture (ISA) which often varies
+based upon some well-defined rules.  There are often
+multiple implementations of the ISA and these may be from
+one or multiple vendors.
+
+On top of variations in the ISA, there may also be variations
+which occur when a CPU core implementation is combined with
+a set of peripherals to form a system on chip.  For example,
+there are many ARM CPU models from numerous semiconductor
+vendors and a wide variety of peripherals.  But at the
+ISA level, they share a common compaability.
+
+RTEMS depends upon this core similarity across the CPU models
+and leverages that to minimize the source code that is specific
+to any particular CPU core implementation or CPU model.
+
+This manual is separate and distinct from the RTEMS Porting
+Guide.  That manual is a guide on porting RTEMS to a new
+architecture.  This manual is focused on the more mundane
+CPU architecture specific issues that may impact
+application development.  For example, if you need to write
+a subroutine in assembly language, it is critical to understand
+the calling conventions for the target architecture.
+
+The first chapter in this manual describes these issues 
+in general terms.  In a sense, it is posing the questions
+one should be aware may need to be answered and understood
+when porting an RTEMS application to a new architecture. 
+Each subsequent chapter gives the answers to those questions
+for a particular CPU architecture.