New manual. First version to CVS. Just starting to see if it builds.

13 files changed, 1846 insertions, 0 deletions

diff --git a/doc/porting/Makefile b/doc/porting/Makefile
new file mode 100644
index 0000000000..2881087623
--- /dev/null
+++ b/doc/porting/Makefile
@@ -0,0 +1,117 @@
+#
+#  COPYRIGHT (c) 1988-1998.
+#  On-Line Applications Research Corporation (OAR).
+#  All rights reserved.
+#
+#  $Id$
+#
+
+PROJECT=porting
+
+include ../Make.config
+
+all: html info ps pdf
+
+dirs:
+	$(make-dirs)
+
+COMMON_FILES=../common/cpright.texi
+FILES=preface.texi developtools.texi sourcecode.texi cpumodels.texi \
+  cpuinit.texi interrupts.texi taskcontext.texi idlethread.texi \
+  prioritybitmap.texi codetuning.texi miscellaneous.texi $(COMMON_FILES)
+
+GENERATED_FILES=preface.texi developtools.texi sourcecode.texi cpumodels.texi \
+  cpuinit.texi interrupts.texi taskcontext.texi idlethread.texi \
+  prioritybitmap.texi codetuning.texi miscellaneous.texi
+
+
+INFOFILES=$(wildcard $(PROJECT) $(PROJECT)-*)
+
+info: dirs $(PROJECT)
+	cp $(PROJECT) $(PROJECT)-* $(INFO_INSTALL)
+
+$(PROJECT): $(FILES)
+	$(MAKEINFO) $(PROJECT).texi
+
+dvi: $(PROJECT).dvi
+ps: dirs $(PROJECT).ps
+pdf: dirs $(PROJECT).pdf
+	
+$(PROJECT).pdf: $(FILES)
+	$(TEXI2PDF) $(PROJECT).texi
+	cp $(PROJECT).pdf $(PDF_INSTALL)
+	
+$(PROJECT).ps: $(PROJECT).dvi
+	dvips -o $(PROJECT).ps $(PROJECT).dvi
+	cp $(PROJECT).ps $(PS_INSTALL)
+
+$(PROJECT).dvi: $(FILES)
+	# $(TEXI2DVI) $(PROJECT).texi
+	texi2dvi -V $(PROJECT).texi
+
+html: dirs $(FILES)
+	-mkdir -p $(WWW_INSTALL)/$(PROJECT)
+	cp rtemsarc.png rtemspie.png states.png $(WWW_INSTALL)/$(PROJECT)
+	$(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \
+	    $(PROJECT).texi
+
+clean:
+	rm -f *.o $(PROG) *.txt core *.html *.pdf
+	rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE)
+	rm -f $(PROJECT) $(PROJECT)-* _* $(GENERATED_FILES)
+
+preface.texi: preface.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" .t
+
+developtools.texi: developtools.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" .t
+
+sourcecode.texi: sourcecode.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" .t
+
+cpumodels.texi: cpumodels.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" .t
+
+cpuinit.texi: cpuinit.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" .t
+
+interrupts.texi: interrupts.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" .t
+
+taskcontext.texi: taskcontext.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" .t
+
+idlethread.texi: idlethread.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" .t
+
+prioritybitmap.texi: prioritybitmap.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" .t
+
+codetuning.texi: codetuning.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" .t
+
+miscellaneous.texi: miscellaneous.t
+	$(BMENU) -p "" \
+	    -u "Top" \
+	    -n "" .t
+
diff --git a/doc/porting/codetuning.t b/doc/porting/codetuning.t
new file mode 100644
index 0000000000..734e720d8c
--- /dev/null
+++ b/doc/porting/codetuning.t
@@ -0,0 +1,147 @@
+@chapter Code Tuning Parameters
+
+@subsection Inline Thread_Enable_dispatch
+
+Should the calls to _Thread_Enable_dispatch be inlined?
+
+If TRUE, then they are inlined.
+
+If FALSE, then a subroutine call is made.
+
+
+Basically this is an example of the classic trade-off of size versus
+speed.  Inlining the call (TRUE) typically increases the size of RTEMS
+while speeding up the enabling of dispatching.
+
+[NOTE: In general, the _Thread_Dispatch_disable_level will only be 0 or 1
+unless you are in an interrupt handler and that interrupt handler invokes
+the executive.] When not inlined something calls _Thread_Enable_dispatch
+which in turns calls _Thread_Dispatch.  If the enable dispatch is inlined,
+then one subroutine call is avoided entirely.]
+
+@example
+#define CPU_INLINE_ENABLE_DISPATCH       FALSE
+@end example
+
+@subsection Inline Thread_queue_Enqueue_priority
+
+Should the body of the search loops in _Thread_queue_Enqueue_priority be
+unrolled one time?  In unrolled each iteration of the loop examines two
+"nodes" on the chain being searched.  Otherwise, only one node is examined
+per iteration.
+
+If TRUE, then the loops are unrolled.
+
+If FALSE, then the loops are not unrolled.
+
+The primary factor in making this decision is the cost of disabling and
+enabling interrupts (_ISR_Flash) versus the cost of rest of the body of
+the loop.  On some CPUs, the flash is more expensive than one iteration of
+the loop body.  In this case, it might be desirable to unroll the loop.  
+It is important to note that on some CPUs, this code is the longest
+interrupt disable period in RTEMS.  So it is necessary to strike a balance
+when setting this parameter.
+
+@example
+#define CPU_UNROLL_ENQUEUE_PRIORITY      TRUE
+@end example
+
+
+@subsection Structure Alignment Optimization
+
+The following macro may be defined to the attribute setting used to force
+alignment of critical RTEMS structures.  On some processors it may make
+sense to have these aligned on tighter boundaries than the minimum
+requirements of the compiler in order to have as much of the critical data
+area as possible in a cache line.  This ensures that the first access of
+an element in that structure fetches most, if not all, of the data
+structure and places it in the data cache.  Modern CPUs often have cache
+lines of at least 16 bytes and thus a single access implicitly fetches
+some surrounding data and places that unreferenced data in the cache.  
+Taking advantage of this allows RTEMS to essentially prefetch critical
+data elements.
+
+The placement of this macro in the declaration of the variables is based
+on the syntactically requirements of the GNU C "__attribute__" extension.  
+For another toolset, the placement of this macro could be incorrect.  For
+example with GNU C, use the following definition of
+CPU_STRUCTURE_ALIGNMENT to force a structures to a 32 byte boundary.
+
+#define CPU_STRUCTURE_ALIGNMENT __attribute__ ((aligned (32)))
+
+To benefit from using this, the data must be heavily used so it will stay
+in the cache and used frequently enough in the executive to justify
+turning this on.  NOTE:  Because of this, only the Priority Bit Map table
+currently uses this feature.
+
+The following illustrates how the CPU_STRUCTURE_ALIGNMENT is defined on
+ports which require no special alignment for optimized access to data
+structures:
+
+@example
+#define CPU_STRUCTURE_ALIGNMENT
+@end example
+
+@subsection Data Alignment Requirements
+
+@subsection Data Element Alignment
+
+The CPU_ALIGNMENT macro should be set to the CPU's worst alignment
+requirement for data types on a byte boundary.  This is typically the
+alignment requirement for a C double. This alignment does not take into
+account the requirements for the stack.
+
+The following sets the CPU_ALIGNMENT macro to 8 which indicates that there
+is a basic C data type for this port which much be aligned to an 8 byte
+boundary.
+
+@example
+#define CPU_ALIGNMENT              8
+@end example
+
+@subsection Heap Element Alignment
+
+The CPU_HEAP_ALIGNMENT macro is set to indicate the byte alignment
+requirement for data allocated by the RTEMS Code Heap Handler.  This
+alignment requirement may be stricter than that for the data types
+alignment specified by CPU_ALIGNMENT.  It is common for the heap to follow
+the same alignment requirement as CPU_ALIGNMENT.  If the CPU_ALIGNMENT is
+strict enough for the heap, then this should be set to CPU_ALIGNMENT. This
+macro is necessary to ensure that allocated memory is properly aligned for
+use by high level language routines.
+
+The following example illustrates how the CPU_HEAP_ALIGNMENT macro is set
+when the required alignment for elements from the heap is the same as the
+basic CPU alignment requirements.
+
+@example
+#define CPU_HEAP_ALIGNMENT         CPU_ALIGNMENT
+@end example
+
+NOTE:  This does not have to be a power of 2.  It does have to be greater
+or equal to than CPU_ALIGNMENT.
+
+@subsection Partition Element Alignment
+
+The CPU_PARTITION_ALIGNMENT macro is set to indicate the byte alignment
+requirement for memory buffers allocated by the RTEMS Partition Manager
+that is part of the Classic API.  This alignment requirement may be
+stricter than that for the data types alignment specified by
+CPU_ALIGNMENT.  It is common for the partition to follow the same
+alignment requirement as CPU_ALIGNMENT.  If the CPU_ALIGNMENT is strict
+enough for the partition, then this should be set to CPU_ALIGNMENT.  This
+macro is necessary to ensure that allocated memory is properly aligned for
+use by high level language routines.
+
+The following example illustrates how the CPU_PARTITION_ALIGNMENT macro is
+set when the required alignment for elements from the RTEMS Partition
+Manager is the same as the basic CPU alignment requirements.
+
+
+@example
+#define CPU_PARTITION_ALIGNMENT    CPU_ALIGNMENT
+@end example
+
+NOTE:  This does not have to be a power of 2.  It does have to be greater
+or equal to than CPU_ALIGNMENT.
+
diff --git a/doc/porting/cpuinit.t b/doc/porting/cpuinit.t
new file mode 100644
index 0000000000..49d9956249
--- /dev/null
+++ b/doc/porting/cpuinit.t
@@ -0,0 +1,85 @@
+@chapter CPU Initialization
+
+This section describes the general CPU and system initialization sequence
+as it pertains to the CPU dependent code.
+
+@section Introduction
+
+XXX general startup sequence description rewritten to make it more
+applicable to CPU depdent code in executive
+
+@section CPU Dependent Configuration Table
+
+The CPU Dependent Configuration Table contains information which tailors
+the behavior of RTEMS base Some of the fields in this table are required
+to be present in all ports of RTEMS.  These fields appear at the beginning
+of the data structure.  Fields past this point may be CPU family and CPU
+model dependent.  For example, a port may add a field to specify the
+default value for an interrupt mask register on the CPU.  This table is
+initialized by the Board Support Package and passed to the
+rtems_initialize_executive or rtems_initialize_executive_early directive.
+
+@example
+typedef struct @{
+  void       (*pretasking_hook)( void );
+  void       (*predriver_hook)( void );
+  void       (*postdriver_hook)( void );
+  void       (*idle_task)( void );
+  boolean      do_zero_of_workspace;
+  unsigned32   idle_task_stack_size;
+  unsigned32   interrupt_stack_size;
+  unsigned32   extra_mpci_receive_server_stack;
+  void *     (*stack_allocate_hook)( unsigned32 );
+  void       (*stack_free_hook)( void* );
+  /* end of fields required on all CPUs */
+
+  unsigned32   some_other_cpu_dependent_info;
+@}   rtems_cpu_table;
+@end example
+
+XXX copy the descriptions of the fields from another CPU supplement
+
+@section Initializing the CPU
+
+The _CPU_Initialize routine performs processor dependent initialization.
+
+@example
+void _CPU_Initialize(
+  rtems_cpu_table  *cpu_table,
+  void            (*thread_dispatch)  /* may be ignored */
+)
+@end example
+
+The thread_dispatch argument is the address of the entry point for the
+routine called at the end of an ISR once it has been decided a context
+switch is necessary.  On some compilation systems it is difficult to call
+a high-level language routine from assembly.  Providing the address of the
+_Thread_ISR_Dispatch routine allows the porter an easy way to obtain this
+critical address and thus provides an easy way to work around this
+limitation on these systems.
+
+If you encounter this problem save the entry point in a CPU dependent
+variable as shown below:
+
+@example
+_CPU_Thread_dispatch_pointer = thread_dispatch;
+@end example
+
+
+During the initialization of the context for tasks with floating point,
+the CPU dependent code is responsible for initializing the floating point
+context.  If there is not an easy way to initialize the FP context during
+Context_Initialize, then it is usually easier to save an "uninitialized"
+FP context here and copy it to the task's during Context_Initialize.  If
+this technique is used to initialize the FP contexts, then it is important
+to ensure that the state of the floating point unit is in a coherent,
+initialized state.
+
+Finally, this routine is responsible for copying the application's CPU
+Table into a locally accessible and modifiable area.  This is shown below:
+
+@example
+_CPU_Table = *cpu_table;
+@end example
+
+
diff --git a/doc/porting/cpumodels.t b/doc/porting/cpumodels.t
new file mode 100644
index 0000000000..1882831bdb
--- /dev/null
+++ b/doc/porting/cpumodels.t
@@ -0,0 +1,8 @@
+@chapter CPU Model Variations
+
+XXX copy some description of the portability model discussion from the
+France97 paper
+XXX enhance thatusing portability presentation from class
+
+@section Introduction
+
diff --git a/doc/porting/developtools.t b/doc/porting/developtools.t
new file mode 100644
index 0000000000..25098732a0
--- /dev/null
+++ b/doc/porting/developtools.t
@@ -0,0 +1,18 @@
+@chapter Development Tools
+
+When porting RTEMS to a new CPU architecture, one will have to have a
+development environment including compiler, assembler, linker, and
+debugger.  The GNU development tool suite used by RTEMS supports most
+modern CPU families.  Often all that is required is to add RTEMS
+configurations for the target CPU family.  RTEMS targets for the GNU tools
+usually start life as little more than aliases for existing embedded
+configurations.  At this point in time, ELF is supported on most of the
+CPU families with a tool target of the form CPU-elf.  If this target is
+not supported by all of the GNU tools, then it will be necessary to
+determine the configuration that makes the best starting point regardless
+of the target object format.
+
+Porting and retargetting the GNU tools is beyond the scope of this manual.  
+The best advice that can be offered is to look at the existing RTEMS
+targets in the tool source and use that as a guideline.
+
diff --git a/doc/porting/idlethread.t b/doc/porting/idlethread.t
new file mode 100644
index 0000000000..98632147fa
--- /dev/null
+++ b/doc/porting/idlethread.t
@@ -0,0 +1,108 @@
+@chapter IDLE Thread
+
+@section Does Idle Thread Have a Floating Point Context?
+
+The setting of the macro CPU_IDLE_TASK_IS_FP is based on the answer to the
+question:  Should the IDLE task have a floating point context?  If the
+answer to this question is TRUE, then the IDLE task has a floating point
+context associated.  This is equivalent to creating a task in the Classic
+API (using rtems_task_create) as a RTEMS_FLOATING_POINT task.  If
+CPU_IDLE_TASK_IS_FP is set to TRUE, then a floating point context switch
+occurs when the IDLE task is switched in and out.  This adds to the
+execution overhead of the system but is necessary on some ports.
+
+If FALSE, then the IDLE task does not have a floating point context.
+
+NOTE: Setting CPU_IDLE_TASK_IS_FP to TRUE negatively impacts the time
+required to preempt the IDLE task from an interrupt because the floating
+point context must be saved as part of the preemption.
+
+The following illustrates how to set this macro:
+
+@example
+#define CPU_IDLE_TASK_IS_FP      FALSE
+@end example
+
+@section CPU Dependent Idle Thread Body
+
+@subsection CPU_PROVIDES_IDLE_THREAD_BODY Macro Setting
+
+The CPU_PROVIDES_IDLE_THREAD_BODY macro setting is based upon the answer
+to the question:  Does this port provide a CPU dependent IDLE task
+implementation?  If the answer to this question is yes, then the
+CPU_PROVIDES_IDLE_THREAD_BODY macro should be set to TRUE, and the routine
+_CPU_Thread_Idle_body must be provided.  This routine overrides the
+default IDLE thread body of _Thread_Idle_body.  If the
+CPU_PROVIDES_IDLE_THREAD_BODY macro is set to FALSE, then the generic
+_Thread_Idle_body is the default IDLE thread body for this port.  
+Regardless of whether or not a CPU dependent IDLE thread implementation is
+provided, the BSP can still override it.
+
+This is intended to allow for supporting processors which have a low power
+or idle mode.  When the IDLE thread is executed, then the CPU can be
+powered down when the processor is idle.
+
+The order of precedence for selecting the IDLE thread body is:
+
+@enumerate
+@item BSP provided
+
+@item CPU dependent (if provided)
+
+@item generic (if no BSP and no CPU dependent)
+
+@end itemize
+
+The following illustrates setting the CPU_PROVIDES_IDLE_THREAD_BODY macro:
+
+@example
+#define CPU_PROVIDES_IDLE_THREAD_BODY    TRUE
+@end example
+
+Implementation details of a CPU model specific IDLE thread body are in the
+next section.
+
+@subsection Idle Thread Body
+
+The _CPU_Thread_Idle_body routine only needs to be provided if the porter
+wishes to include a CPU dependent IDLE thread body.  If the port includes
+a CPU dependent implementation of the IDLE thread body, then the
+CPU_PROVIDES_IDLE_THREAD_BODY macro should be defined to TRUE.  This
+routine is prototyped as follows:
+
+@example
+void _CPU_Thread_Idle_body( void );
+@end example
+
+As mentioned above, RTEMS does not require that a CPU dependent IDLE
+thread body be provided as part of the port.  If
+CPU_PROVIDES_IDLE_THREAD_BODY is defined to FALSE, then the CPU
+independent algorithm is used.  This algorithm consists of a "branch to
+self" which is implemented in the XXX routine as follows.
+
+@example
+XXX check name and exact implementation
+void _Thread_Idle_body( void )
+@{
+  while( 1 ) ;
+@}
+@end example
+
+If the CPU dependent IDLE thread body is implementation centers upon using
+a "halt", "idle", or "shutdown" instruction, then don't forget to put it
+in an infinite loop as the CPU will have to reexecute this instruction
+each time the IDLE thread is dispatched.
+
+@example
+void _CPU_Thread_Idle_body( void )
+@{
+
+  for( ; ; )
+    /* insert your "halt" instruction here */ ;
+@}
+@end example
+
+Be warned. Some processors with onboard DMA have been known to stop the
+DMA if the CPU were put in IDLE mode.  This might also be a problem with
+other on-chip peripherals.  So use this hook with caution.
+
diff --git a/doc/porting/interrupts.t b/doc/porting/interrupts.t
new file mode 100644
index 0000000000..8a2348eaa6
--- /dev/null
+++ b/doc/porting/interrupts.t
@@ -0,0 +1,394 @@
+@chapter Interrupts
+
+@section Introduction
+
+@section Interrupt Levels
+
+RTEMS is designed assuming that a CPU family has a level associated with
+interrupts.  Interrupts below the current interrupt level are masked and
+do not interrupt the CPU until the interrupt level is lowered.  This
+design provides for 256 distinct interrupt levels even though most CPU
+implementations support far fewer levels.  Interrupt level 0 is assumed to
+map to the hardware settings for all interrupts enabled.
+
+Over the years that RTEMS has been available, there has been much
+discussion on how to handle CPU families which support very few interrupt
+levels such as the i386, PowerPC, and HP-PA RISC. XXX
+
+@subsection Interrupt Level Mask
+
+The CPU_MODES_INTERRUPT_MASK macro defines the number of bits actually used in the interrupt field of the task mode.  How those bits map to the CPU interrupt levels is defined by the routine _CPU_ISR_Set_level().
+
+The following illustrates how the CPU_MODES_INTERRUPT_MASK is set on a CPU
+family like the Intel i386 where the CPU itself only recognizes two
+interrupt levels - enabled and disabled.
+
+@example
+#define CPU_MODES_INTERRUPT_MASK   0x00000001
+@end example
+
+
+@subsection Obtaining the Current Interrupt Level
+
+The _CPU_ISR_Get_level function returns the current interrupt level.
+
+@example
+unsigned32 _CPU_ISR_Get_level( void )
+@end example
+
+@subsection Set the Interrupt Level
+
+The _CPU_ISR_Set_level routine maps the interrupt level in the Classic API
+task mode onto the hardware that the CPU actually provides.  Currently,
+interrupt levels that do not map onto the CPU in a generic fashion are
+undefined.  Someday, it would be nice if these were "mapped" by the
+application via a callout.  For example, the Motorola m68k has 8 levels 0
+- 7, and levels 8 - 255 are currently undefined.  Levels 8 - 255 would be
+available for bsp/application specific meaning. This could be used to
+manage a programmable interrupt controller via the rtems_task_mode
+directive.
+
+The following is a dummy implementation of the _CPU_ISR_Set_level routine:
+
+@example
+#define _CPU_ISR_Set_level( new_level ) \
+  @{ \
+  @}
+@end example
+
+The following is the implementation from the Motorola M68K:
+
+@example
+XXX insert m68k implementation here
+@end example
+
+
+@subsection Disable Interrupts
+
+The _CPU_ISR_Disable routine disable all external interrupts.  It returns
+the previous interrupt level in the single parameter _isr_cookie.  This
+routine is used to disable interrupts during a critical section in the
+RTEMS executive.  Great care is taken inside the executive to ensure that
+interrupts are disabled for a minimum length of time.  It is important to
+note that the way the previous level is returned forces the implementation
+to be a macro that translates to either inline assembly language or a
+function call whose return value is placed into _isr_cookie.
+
+It is important for the porter to realize that the value of _isr_cookie
+has no defined meaning except that it is the most convenient format for
+the _CPU_ISR_Disable, _CPU_ISR_Enable, and _CPU_ISR_Disable routines to
+manipulate.  It is typically the contents of the processor status
+register.  It is NOT the same format as manipulated by the
+_CPU_ISR_Get_level and _CPU_ISR_Set_level routines. The following is a
+dummy implementation that simply sets the previous level to 0.
+
+@example
+#define _CPU_ISR_Disable( _isr_cookie ) \
+  @{ \
+    (_isr_cookie) = 0;   /* do something to prevent warnings */ \
+  @}
+@end example
+
+The following is the implementation from the Motorola M68K port:
+
+@example
+XXX insert m68k port here
+@end example
+
+@subsection Enable Interrupts
+
+The _CPU_ISR_Enable routines enables interrupts to the previous level
+(returned by _CPU_ISR_Disable).  This routine is invoked at the end of an
+RTEMS critical section to reenable interrupts.  The parameter _level is
+not modified but indicates that level that interrupts should be enabled
+to.  The following illustrates a dummy implementation of the
+_CPU_ISR_Enable routine:
+
+@example
+#define _CPU_ISR_Enable( _isr_cookie )  \
+  @{ \
+  @}
+@end example
+
+The following is the implementation from the Motorola M68K port:
+
+@example
+XXX insert m68k version here
+@end example
+
+
+@subsection Flash Interrupts
+
+The _CPU_ISR_Flash routine temporarily restores the interrupt to _level
+before immediately disabling them again.  This is used to divide long
+RTEMS critical sections into two or more parts.  This routine is always
+preceded by a call to _CPU_ISR_Disable and followed by a call to
+_CPU_ISR_Enable.  The parameter _level is not modified.
+
+The following is a dummy implementation of the _CPU_ISR_Flash routine:
+
+@example
+#define _CPU_ISR_Flash( _isr_cookie ) \
+  @{ \
+  @}
+@end example
+
+The following is the implementation from the Motorola M68K port:
+
+@example
+XXX insert m68k version here
+@end example
+
+
+@section Interrupt Stack Management
+
+@subsection Hardware or Software Managed Interrupt Stack
+
+The setting of the CPU_HAS_SOFTWARE_INTERRUPT_STACK indicates whether the
+interrupt stack is managed by RTEMS in software or the CPU has direct
+support for an interrupt stack.  If RTEMS is to manage a dedicated
+interrupt stack in software, then this macro should be set to TRUE and the
+memory for the software managed interrupt stack is allocated in
+_Interrupt_Manager_initialization.  If this macro is set to FALSE, then
+RTEMS assumes that the hardware managed interrupt stack is supported by
+this CPU.  If the CPU has a hardware managed interrupt stack, then the
+porter has the option of letting the BSP allcoate and initialize the
+interrupt stack or letting RTEMS do this.  If RTEMS is to allocate the
+memory for the interrupt stack, then the macro
+CPU_ALLOCATE_INTERRUPT_STACK should be set to TRUE.  If this macro is set
+to FALSE, then it is the responsibility of the BSP to allocate the memory
+for this stack and initialize it.
+
+If the CPU does not support a dedicated interrupt stack, then the porter
+has two options: (1) execute interrupts on the stack of the interrupted
+task, and (2) have RTEMS manage a dedicated interrupt stack.
+
+NOTE: If CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE, then the macro
+CPU_ALLOCATE_INTERRUPT_STACK should also be set to TRUE.
+
+Only one of CPU_HAS_SOFTWARE_INTERRUPT_STACK and
+CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE.  It is possible
+that both are FALSE for a particular CPU.  Although it is unclear what
+that would imply about the interrupt processing procedure on that CPU.
+
+@subsection Allocation of Interrupt Stack Memory
+
+Whether or not the interrupt stack is hardware or software managed, RTEMS
+may allocate memory for the interrupt stack from the Executive Workspace.  
+If RTEMS is going to allocate the memory for a dedicated interrupt stack
+in the Interrupt Manager, then the macro CPU_ALLOCATE_INTERRUPT_STACK
+should be set to TRUE.
+
+NOTE: This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE.
+
+@example
+#define CPU_ALLOCATE_INTERRUPT_STACK TRUE
+@end example
+
+If the CPU_HAS_SOFTWARE_INTERRUPT_STACK macro is set to TRUE, then RTEMS automatically allocates the stack memory in the initialization of the Interrupt Manager and the switch to that stack is performed in _ISR_Handler on the outermost interrupt.  The _CPU_Interrupt_stack_low and _CPU_Interrupt_stack_high variables contain the addresses of the the lowest and highest addresses of the memory allocated for the interrupt stack.  Although technically only one of these addresses is required to switch to the interrupt stack, by always providing both addresses, the port has more options avaialble to it without requiring modifications to the portable parts of the executive.  Whether the stack  grows up or down, this give the CPU dependent code the option of picking the version it wants to use.
+
+@example
+SCORE_EXTERN void               *_CPU_Interrupt_stack_low;
+SCORE_EXTERN void               *_CPU_Interrupt_stack_high;
+@end example
+
+NOTE: These two variables are required if the macro
+CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE.
+
+@subsection Install the Interrupt Stack
+
+The _CPU_Install_interrupt_stack routine XXX
+
+This routine installs the hardware interrupt stack pointer.
+
+NOTE:  It need only be provided if CPU_HAS_HARDWARE_INTERRUPT_STAC is TRUE.
+
+@example
+void _CPU_Install_interrupt_stack( void )
+@end example
+
+
+@section ISR Installation
+
+@subsection Install a Raw Interrupt Handler
+
+The _CPU_ISR_install_raw_handler XXX
+ 
+@example
+void _CPU_ISR_install_raw_handler(
+  unsigned32  vector,
+  proc_ptr    new_handler,
+  proc_ptr   *old_handler
+)
+@end example
+
+This is where we install the interrupt handler into the "raw" interrupt
+table used by the CPU to dispatch interrupt handlers.
+
+@subsection Interrupt Context
+
+@subsection Maximum Number of Vectors
+
+There are two related macros used to defines the number of entries in the
+_ISR_Vector_table managed by RTEMS.  The macro
+CPU_INTERRUPT_NUMBER_OF_VECTORS is the actual number of vectors supported
+by this CPU model.  The second macro is the
+CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER.  Since the table is zero-based, this
+indicates the highest vector number which can be looked up in the table
+and mapped into a user provided handler.
+
+@example
+#define CPU_INTERRUPT_NUMBER_OF_VECTORS      32
+#define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER \
+        (CPU_INTERRUPT_NUMBER_OF_VECTORS - 1)
+@end example
+
+
+@subsection Install RTEMS Interrupt Handler
+
+The _CPU_ISR_install_vector routine installs the RTEMS handler for the
+specified vector.
+
+XXX Input parameters:
+vector      - interrupt vector number
+old_handler - former ISR for this vector number
+new_handler - replacement ISR for this vector number
+ 
+@example
+void _CPU_ISR_install_vector(
+  unsigned32  vector,
+  proc_ptr    new_handler,
+  proc_ptr   *old_handler
+)
+@end example
+
+@example
+*old_handler = _ISR_Vector_table[ vector ];
+@end example
+
+If the interrupt vector table is a table of pointer to isr entry points,
+then we need to install the appropriate RTEMS interrupt handler for this
+vector number.
+ 
+@example
+_CPU_ISR_install_raw_handler( vector, new_handler, old_handler );
+@end example
+
+We put the actual user ISR address in _ISR_vector_table.  This will be
+used by the _ISR_Handler so the user gets control.
+
+@example
+_ISR_Vector_table[ vector ] = new_handler;
+@end example
+
+@section Interrupt Processing
+
+@subsection Interrupt Frame Data Structure
+
+When an interrupt occurs, it is the responsibility of the interrupt
+dispatching software to save the context of the processor such that an ISR
+written in a high-level language (typically C) can be invoked without
+damaging the state of the task that was interrupted.  In general, this
+results in the saving of registers which are NOT preserved across
+subroutine calls as well as any special interrupt state.  A port should
+define the CPU_Interrupt_frame structure so that application code can
+examine the saved state.
+
+@example
+typedef struct @{
+    unsigned32 not_preserved_register_1;
+    unsigned32 special_interrupt_register;
+@} CPU_Interrupt_frame;
+@end example
+
+
+@subsection Interrupt Dispatching
+
+The _ISR_Handler routine provides the RTEMS interrupt management.
+ 
+@example
+void _ISR_Handler()
+@end example
+
+This discussion ignores a lot of the ugly details in a real implementation
+such as saving enough registers/state to be able to do something real.  
+Keep in mind that the goal is to invoke a user's ISR handler which is
+written in C.  That ISR handler uses a known set of registers thus
+allowing the ISR to preserve only those that would normally be corrupted
+by a subroutine call.
+
+Also note that the exact order is to a large extent flexible.  Hardware
+will dictate a sequence for a certain subset of _ISR_Handler while
+requirements for setting the RTEMS state variables that indicate the
+interrupt nest level (XX) and dispatching disable level (XXX) will also
+restrict the allowable order.
+
+Upon entry to the "common" _ISR_Handler, the vector number must be
+available.  On some CPUs the hardware puts either the vector number or the
+offset into the vector table for this ISR in a known place.  If the
+hardware does not provide this information, then the assembly portion of
+RTEMS for this port will contain a set of distinct interrupt entry points
+which somehow place the vector number in a known place (which is safe if
+another interrupt nests this one) and branches to _ISR_Handler.
+
+@example
+save some or all context on stack
+may need to save some special interrupt information for exit
+
+#if ( CPU_HAS_SOFTWARE_INTERRUPT_STACK == TRUE )
+    if ( _ISR_Nest_level == 0 )
+        switch to software interrupt stack
+#endif
+_ISR_Nest_level++;
+_Thread_Dispatch_disable_level++;
+(*_ISR_Vector_table[ vector ])( vector );
+--_ISR_Nest_level;
+if ( _ISR_Nest_level )
+    goto the label "exit interrupt (simple case)"
+#if ( CPU_HAS_SOFTWARE_INTERRUPT_STACK == TRUE )
+    restore stack
+#endif
+ 
+if ( !_Context_Switch_necessary )
+    goto the label "exit interrupt (simple case)"
+  
+if ( !_ISR_Signals_to_thread_executing )
+    _ISR_Signals_to_thread_executing = FALSE;
+    goto the label "exit interrupt (simple case)"
+
+call _Thread_Dispatch() or prepare to return to _ISR_Dispatch
+prepare to get out of interrupt
+return from interrupt  (maybe to _ISR_Dispatch)
+ 
+LABEL "exit interrupt (simple case):
+ prepare to get out of interrupt
+ return from interrupt
+@end example
+  
+@subsection ISR Invoked with Frame Pointer
+
+Does the RTEMS invoke the user's ISR with the vector number and a pointer
+to the saved interrupt frame (1) or just the vector number (0)?
+
+@example
+#define CPU_ISR_PASSES_FRAME_POINTER 0
+@end example
+
+NOTE: It is desirable to include a pointer to the interrupt stack frame as
+an argument to the interrupt service routine.  Eventually, it would be
+nice if all ports included this parameter.
+
+@subsection Pointer to _Thread_Dispatch Routine
+
+With some compilation systems, it is difficult if not impossible to call a
+high-level language routine from assembly language.  This is especially
+true of commercial Ada compilers and name mangling C++ ones.  This
+variable can be optionally defined by the CPU porter and contains the
+address of the routine _Thread_Dispatch.  This can make it easier to
+invoke that routine at the end of the interrupt sequence (if a dispatch is
+necessary).
+
+@example
+void (*_CPU_Thread_dispatch_pointer)();
+@end example
+
diff --git a/doc/porting/miscellaneous.t b/doc/porting/miscellaneous.t
new file mode 100644
index 0000000000..a603ca8554
--- /dev/null
+++ b/doc/porting/miscellaneous.t
@@ -0,0 +1,162 @@
+@chapter Miscellaneous
+
+@section Fatal Error Default Handler
+
+The _CPU_Fatal_halt routine is the default fatal error handler. This
+routine copies _error into a known place -- typically a stack location or
+a register, optionally disables interrupts, and halts/stops the CPU.  It
+is prototyped as follows and is often implemented as a macro:
+
+@example
+void _CPU_Fatal_halt(
+    unsigned32 _error
+);
+@end example
+
+@section Processor Endianness
+
+Endianness refers to the order in which numeric values are stored in
+memory by the microprocessor.  Big endian architectures store the most
+significant byte of a multi-byte numeric value in the byte with the lowest
+address.  This results in the hexadecimal value 0x12345678 being stored as
+0x12345678 with 0x12 in the byte at offset zero, 0x34 in the byte at
+offset one, etc..  The Motorola M68K and numerous RISC processor families
+is big endian.  Conversely, little endian architectures store the least
+significant byte of a multi-byte numeric value in the byte with the lowest
+address.  This results in the hexadecimal value 0x12345678 being stored as
+0x78563412 with 0x78 in the byte at offset zero, 0x56 in the byte at
+offset one, etc..  The Intel ix86 family is little endian.  
+Interestingly, some CPU models within the PowerPC and MIPS architectures
+can be switched between big and little endian modes.  Most embedded
+systems use these families strictly in big endian mode.
+
+RTEMS must be informed of the byte ordering for this microprocessor family
+and, optionally, endian conversion routines may be provided as part of the
+port.  Conversion between endian formats is often necessary in
+multiprocessor environments and sometimes needed when interfacing with
+peripheral controllers.
+
+@subsection Specifying Processor Endianness
+
+The CPU_BIG_ENDIAN and CPU_LITTLE_ENDIAN are set to specify the endian
+format used by this microprocessor.  These macros should not be set to the
+same value.  The following example illustrates how these macros should be
+set on a processor family that is big endian.
+
+@example
+#define CPU_BIG_ENDIAN                           TRUE
+#define CPU_LITTLE_ENDIAN                        FALSE
+@end example
+
+@subsection Optional Endian Conversion Routines
+
+In a networked environment, each program communicating must agree on the
+format of data passed between the various systems in the networked
+application.  Routines such as ntohl() and htonl() are used to convert
+between the common network format and the native format used on this
+particular host system.  Although RTEMS has a portable implementation of
+these endian conversion routines, it is often possible to implement these
+routines more efficiently in a processor specific fashion.
+
+The CPU_HAS_OWN_HOST_TO_NETWORK_ROUTINES is set to TRUE when the port
+provides its own implementation of the network to host and host to network
+family of routines.  This set of routines include the following:
+
+@itemize @bullet
+@item XXX list of routines in bullets
+@end itemize
+
+The following example illustrates how this macro should be set when the
+generic, portable implementation of this family of routines is to be used
+by this port:
+
+@example
+#define CPU_HAS_OWN_HOST_TO_NETWORK_ROUTINES FALSE
+@end example
+
+@section Extra Stack for MPCI Receive Thread
+
+The CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK macro is set to the amount of
+stack space above the minimum thread stack space required by the MPCI
+Receive Server Thread.  This macro is needed because in a multiprocessor
+system the MPCI Receive Server Thread must be able to process all
+directives.
+
+@example
+#define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0
+@end example
+
+@subsection Endian Swap Unsigned Integers
+
+The port should provide routines to swap sixteen (CPU_swap_u16) and
+thirty-bit (CPU_swap_u32) unsigned integers.  These are primarily used in
+two areas of RTEMS - multiprocessing support and the network endian swap
+routines.  The CPU_swap_u32 routine must be implemented as a static
+routine rather than a macro because its address is taken and used
+indirectly.  On the other hand, the CPU_swap_u16 routine may be
+implemented as a macro.
+
+Some CPUs have special instructions that swap a 32-bit quantity in a
+single instruction (e.g. i486).  It is probably best to avoid an "endian
+swapping control bit" in the CPU.  One good reason is that interrupts
+would probably have to be disabled to insure that an interrupt does not
+try to access the same "chunk" with the wrong endian.  Another good reason
+is that on some CPUs, the endian bit endianness for ALL fetches -- both
+code and data -- so the code will be fetched incorrectly.
+
+The following is an implementation of the CPU_swap_u32 routine that will
+work on any CPU.  It operates by breaking the unsigned thirty-two bit
+integer into four byte-wide quantities and reassemblying them.
+
+@example
+static inline unsigned int CPU_swap_u32(
+  unsigned int value
+)
+@{
+  unsigned32 byte1, byte2, byte3, byte4, swapped;
+ 
+  byte4 = (value >> 24) & 0xff;
+  byte3 = (value >> 16) & 0xff;
+  byte2 = (value >> 8)  & 0xff;
+  byte1 =  value        & 0xff;
+ 
+  swapped = (byte1 << 24) | (byte2 << 16) | (byte3 << 8) | byte4;
+  return( swapped );
+@}
+@end example
+
+Although the above implementation is portable, it is not particularly
+efficient.  So if there is a better way to implement this on a particular
+CPU family or model, please do so.  The efficiency of this routine has
+significant impact on the efficiency of the multiprocessing support code
+in the shared memory driver and in network applications using the ntohl()
+family of routines.
+
+Most microprocessor families have rotate instructions which can be used to
+greatly improve the CPU_swap_u32 routine.  The most common way to do this
+is to:
+
+@example
+swap least significant two bytes with 16-bit rotate
+swap upper and lower 16-bits
+swap most significant two bytes with 16-bit rotate
+@end example
+
+Some CPUs have special instructions that swap a 32-bit quantity in a
+single instruction (e.g. i486).  It is probably best to avoid an "endian
+swapping control bit" in the CPU.  One good reason is that interrupts
+would probably have to be disabled to insure that an interrupt does not
+try to access the same "chunk" with the wrong endian.  Another good reason
+is that on some CPUs, the endian bit endianness for ALL fetches -- both
+code and data -- so the code will be fetched incorrectly.
+
+Similarly, here is a portable implementation of the CPU_swap_u16 routine.  
+Just as with the CPU_swap_u32 routine, the porter should provide a better
+implementation if possible.
+
+@example
+#define CPU_swap_u16( value ) \
+  (((value&0xff) << 8) | ((value >> 8)&0xff))
+@end example
+
+
diff --git a/doc/porting/porting.texi b/doc/porting/porting.texi
new file mode 100644
index 0000000000..7d01a1c6a6
--- /dev/null
+++ b/doc/porting/porting.texi
@@ -0,0 +1,139 @@
+\input texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename porting
+@syncodeindex vr fn
+@synindex ky cp
+@paragraphindent 0
+@c @smallbook
+@c %**end of header
+
+@c
+@c  COPYRIGHT (c) 1988-1998.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@c
+@c   Master file for the Porting Guide
+@c
+
+@c Joel's Questions
+@c
+@c  1.  Why does paragraphindent only impact makeinfo?
+@c  2.  Why does paragraphindent show up in HTML?
+@c
+
+@include ../common/setup.texi
+
+@ignore
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* RTEMS Porting Guide: (porting).             The Porting Guide
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+@end ignore
+
+@c variable substitution info:
+@c
+@set is-C
+@clear is-Ada
+@set LANGUAGE C
+@set STRUCTURE structure
+@set ROUTINE function
+@set OR |
+@set RPREFIX RTEMS_
+@set DIRPREFIX rtems_
+@c the language is @value{LANGUAGE}
+@c NOTE:  don't use underscore in the name
+@c
+
+@c
+@c  Title Page Stuff
+@c
+
+@set edition @value{RTEMS-EDITION}
+@set version @value{RTEMS-VERSION}
+@set update-date @value{RTEMS-UPDATE-DATE}
+@set update-month @value{RTEMS-UPDATE-MONTH}
+
+@c
+@c  I don't really like having a short title page.  --joel
+@c
+@c @shorttitlepage RTEMS Porting Guide
+
+@setchapternewpage odd
+@settitle RTEMS Porting Guide
+@titlepage
+@finalout
+
+@title RTEMS Porting Guide
+@subtitle Edition @value{edition}, for RTEMS @value{version}
+@sp 1
+@subtitle @value{update-month}
+@author On-Line Applications Research Corporation
+@page
+@include ../common/cpright.texi
+@end titlepage
+
+@c  This prevents a black box from being printed on "overflow" lines.
+@c  The alternative is to rework a sentence to avoid this problem.
+
+@include preface.texi
+@include developtools.texi
+@include sourcecode.texi
+@include cpumodels.texi
+@include cpuinit.texi
+@include interrupts.texi
+@include taskcontext.texi
+@include idlethread.texi
+@include prioritybitmap.texi
+@include codetuning.texi
+@include miscellaneous.texi
+@ifinfo
+@node Top, Preface, (dir), (dir)
+@top porting
+
+This is the online version of the RTEMS Porting Guide.
+
+@menu
+* Preface::
+* Development Tools::
+* Source Code Organization::
+* CPU Model Variations::
+* CPU Initialization::
+* Interrupts::
+* Task Context::
+* IDLE Thread::
+* Priority Bitmap Manipulation::
+* Code Tuning Parameters::
+* Miscellaneous::
+* Command and Variable Index::
+* Concept Index::
+@end menu
+
+@end ifinfo
+@c 
+@c 
+@c Need to copy the emacs stuff and "trailer stuff" (index, toc) into here
+@c
+
+@node Command and Variable Index, Concept Index, , Top
+@unnumbered Command and Variable Index
+
+There are currently no Command and Variable Index entries.
+
+@c @printindex fn
+
+@node Concept Index, , Command and Variable Index, Top
+@unnumbered Concept Index
+
+There are currently no Concept Index entries.
+@c @printindex cp
+
+@contents
+@bye
+
diff --git a/doc/porting/preface.t b/doc/porting/preface.t
new file mode 100644
index 0000000000..b180a63b4c
--- /dev/null
+++ b/doc/porting/preface.t
@@ -0,0 +1,32 @@
+
+@chapter Preface
+
+The purpose of this manual is to provide a roadmap to those people porting
+RTEMS to a new CPU family. This process includes a variety of activities
+including the following:
+
+@itemize @bullet
+
+@item targeting the GNU development tools
+
+@item porting the RTEMS executive code
+
+@item developing a Board Support Package
+
+@item writing an RTEMS CPU Supplement manual for the completed port.
+
+@end itemize
+
+This document focuses on the process of actually porting the RTEMS
+executive code proper.  Each of the data structures, routines, and macro
+definitions required of a port of RTEMS is described in this document.
+
+Porting any operating system, including RTEMS, requires knowledge of the
+operating system, target CPU architecture, and debug environment.  It is
+very desirable to have a CPU simulator or hardware emulator when debugging
+the port.  This manual assumes that the user is familiar with building and
+using RTEMS, the C programming language, and the target CPU architecture.  
+It is desirable to be familiar with the assembly language for the target
+CPU family but since only a limited amount of assembly is required to port
+RTEMS.
+
diff --git a/doc/porting/prioritybitmap.t b/doc/porting/prioritybitmap.t
new file mode 100644
index 0000000000..343b5af20d
--- /dev/null
+++ b/doc/porting/prioritybitmap.t
@@ -0,0 +1,158 @@
+@chapter Priority Bitmap Manipulation
+
+@section Introduction
+
+The RTEMS chain of ready tasks is implemented as an array of FIFOs with
+each priority having its own FIFO.  This makes it very efficient to
+determine the first and last ready task at each priority.  In addition,
+blocking a task only requires appending the task to the end of the FIFO
+for its priority rather than a lengthy search down a single chain of all
+ready tasks.  This works extremely well except for one problem.  When the
+currently executing task blocks, there may be no easy way to determine
+what is the next most important ready task.  If the blocking task was the
+only ready task at its priority, then RTEMS must search all of the FIFOs
+in the ready chain to determine the highest priority with a ready task.
+
+RTEMS uses a bitmap array to efficiently solve this problem.  The state of
+each bit in the priority map bit array indicates whether or not there is a
+ready task at that priority.  The bit array can be efficiently searched to
+determine the highest priority ready task.  This family of data type and
+routines is used to maintain and search the bit map array.
+
+@section _Priority_Bit_map_control Type
+
+The _Priority_Bit_map_Control type is the fundamental data type of the
+priority bit map array used to determine which priorities have ready
+tasks.  This type may be either 16 or 32 bits wide although only the 16
+least significant bits will be used.  The data type is based upon what is
+the most efficient type for this CPU to manipulate.  For example, some
+CPUs have bit scan instructions that only operate on a particular size of
+data.  In this case, this type will probably be defined to work with this
+instruction.
+
+@section Find First Bit Routine
+
+The _CPU_Bitfield_Find_first_bit routine sets _output to the bit number of
+the first bit set in _value.  _value is of CPU dependent type
+Priority_Bit_map_control.  A stub version of this routine is as follows:
+
+@example
+#define _CPU_Bitfield_Find_first_bit( _value, _output ) \
+  @{ \
+    (_output) = 0;   /* do something to prevent warnings */ \
+  @}
+@end example
+
+There are a number of variables in using a "find first bit" type
+instruction.
+
+@enumerate
+
+@item What happens when run on a value of zero?
+
+@item Bits may be numbered from MSB to LSB or vice-versa.
+
+@item The numbering may be zero or one based.
+
+@item The "find first bit" instruction may search from MSB or LSB.
+
+@end itemize
+
+RTEMS guarantees that (1) will never happen so it is not a concern.  
+Cases (2),(3), (4) are handled by the macros _CPU_Priority_mask() and
+_CPU_Priority_bits_index().  These three form a set of routines which must
+logically operate together.  Bits in the _value are set and cleared based
+on masks built by CPU_Priority_mask().  The basic major and minor values
+calculated by _Priority_Major() and _Priority_Minor() are "massaged" by
+_CPU_Priority_bits_index() to properly range between the values returned
+by the "find first bit" instruction.  This makes it possible for
+_Priority_Get_highest() to calculate the major and directly index into the
+minor table.  This mapping is necessary to ensure that 0 (a high priority
+major/minor) is the first bit found.
+
+This entire "find first bit" and mapping process depends heavily on the
+manner in which a priority is broken into a major and minor components
+with the major being the 4 MSB of a priority and minor the 4 LSB.  Thus (0
+<< 4) + 0 corresponds to priority 0 -- the highest priority.  And (15 <<
+4) + 14 corresponds to priority 254 -- the next to the lowest priority.
+
+If your CPU does not have a "find first bit" instruction, then there are
+ways to make do without it.  Here are a handful of ways to implement this
+in software:
+
+@itemize @bullet
+
+@item  a series of 16 bit test instructions
+
+@item  a "binary search using if's"
+
+@item  the following algorithm based upon a 16 entry lookup table.  In this pseudo-code, bit_set_table[16] has values which indicate the first bit set:
+
+@example
+_number = 0 if _value > 0x00ff
+     _value >>=8
+     _number = 8;
+ if _value > 0x0000f
+     _value >=8
+     _number += 4
+ 
+_number += bit_set_table[ _value ]
+@end example
+
+@end itemize
+
+The following illustrates how the CPU_USE_GENERIC_BITFIELD_CODE macro may
+be so the port can use the generic implementation of this bitfield code.  
+This can be used temporarily during the porting process to avoid writing
+these routines until the end.  This results in a functional although lower
+performance port.  This is perfectly acceptable during development and
+testing phases.
+
+@example
+#define CPU_USE_GENERIC_BITFIELD_CODE TRUE
+#define CPU_USE_GENERIC_BITFIELD_DATA TRUE
+@end example
+
+Eventually, CPU specific implementations of these routines are usually
+written since they dramatically impact the performance of blocking
+operations.  However they may take advantage of instructions which are not
+available on all models in the CPU family.  In this case, one might find
+something like this stub example did:
+
+@example
+#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
+#define _CPU_Bitfield_Find_first_bit( _value, _output ) \
+  @{ \
+    (_output) = 0;   /* do something to prevent warnings */ \
+  @}
+#endif
+@end example
+
+@section Build Bit Field Mask
+
+The _CPU_Priority_Mask routine builds the mask that corresponds to the bit
+fields searched by _CPU_Bitfield_Find_first_bit().  See the discussion of
+that routine for more details.
+
+The following is a typical implementation when the
+_CPU_Bitfield_Find_first_bit searches for the most significant bit set:
+
+@example
+#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
+#define _CPU_Priority_Mask( _bit_number ) \
+  ( 1 << (_bit_number) )
+#endif
+@end example
+
+@section Bit Scan Support
+
+The _CPU_Priority_bits_index routine translates the bit numbers returned by _CPU_Bitfield_Find_first_bit() into something suitable for use as a major or minor component of a priority.  For example, the find first bit routine may number the bits in a way that is difficult to map into the major and minor components of the priority.  This routine allows that unwieldy form to be converted into something easier to process.  See the discussion of that routine for more details.
+
+@example
+#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
+#define _CPU_Priority_bits_index( _priority ) \
+  (_priority)
+#endif
+@end example
+
+
diff --git a/doc/porting/sourcecode.t b/doc/porting/sourcecode.t
new file mode 100644
index 0000000000..211218e56a
--- /dev/null
+++ b/doc/porting/sourcecode.t
@@ -0,0 +1,15 @@
+@chapter Source Code Organization
+
+This section describes the organization of the source code within RTEMS
+that is CPU family and CPU model dependent.
+
+@section Introduction
+
+The CPU family dependent files associated with a port of the RTEMS
+executive code proper to a particular processor family are found in
+c/src/exec/score/cpu.  Support code for this port as well as processor
+dependent code which may be reused across multiple Board Support Packages
+is found in c/src/lib/libcpu.
+
+XXX list the files and directories here
+
diff --git a/doc/porting/taskcontext.t b/doc/porting/taskcontext.t
new file mode 100644
index 0000000000..0b11d1b297
--- /dev/null
+++ b/doc/porting/taskcontext.t
@@ -0,0 +1,463 @@
+@chapter Task Context
+
+@section Introduction
+
+@section Task Stacks
+
+@subsection Direction of Stack Growth
+
+The CPU_STACK_GROWS_UP macro is set based upon the answer to the following
+question: Does the stack grow up (toward higher addresses) or down (toward
+lower addresses)?  If the stack grows upward in memory, then this macro
+should be set to TRUE.  Otherwise, it should be set to FALSE to indicate
+that the stack grows downward toward smaller addresses.
+
+The following illustrates how the CPU_STACK_GROWS_UP macro is set:
+
+@example
+#define CPU_STACK_GROWS_UP               TRUE
+@end example
+
+@subsection Minimum Task Stack Size
+
+The CPU_STACK_MINIMUM_SIZE macro should be set to the minimum size of each
+task stack.  This size is specified as the number of bytes.  This minimum
+stack size should be large enough to run all RTEMS tests.  The minimum
+stack size is chosen such that a "reasonable" small application should not
+have any problems.  Choosing a minimum stack size that is too small will
+result in the RTEMS tests "blowing" their stack and not executing
+properly.
+
+There are many reasons a task could require a stack size larger than the
+minimum.  For example, a task could have a very deep call path or declare
+large data structures on the stack.  Tasks which utilize C++ exceptions
+tend to require larger stacks as do Ada tasks.
+
+The following illustrates setting the minimum stack size to 4 kilobytes
+per task.
+
+@example
+#define CPU_STACK_MINIMUM_SIZE          (1024*4)
+@end example
+
+@subsection Stack Alignment Requirements
+
+The CPU_STACK_ALIGNMENT macro is set to indicate the byte alignment
+requirement for the stack.  This alignment requirement may be stricter
+than that for the data types alignment specified by CPU_ALIGNMENT.  If the
+CPU_ALIGNMENT is strict enough for the stack, then this should be set to
+0.
+
+The following illustrates how the CPU_STACK_ALIGNMENT macro should be set
+when there are no special requirements:
+
+@example
+#define CPU_STACK_ALIGNMENT        0
+@end example
+
+NOTE:  This must be a power of 2 either 0 or greater than CPU_ALIGNMENT. [XXX is this true?]
+
+@section Task Context
+
+Associated with each task is a context that distinguishes it from other
+tasks in the system and logically gives it its own scratch pad area for
+computations.  In addition, when an interrupt occurs some processor
+context information must be saved and restored.  This is managed in RTEMS
+as three items:
+
+@itemize @bullet
+
+@item Basic task level context (e.g. the Context_Control structure)
+
+@item Floating point task context (e.g. Context_Control_fp structure)
+
+@item Interrupt level context (e.g.  the Context_Control_interrupt
+structure)
+
+@end itemize
+
+The integer and floating point context structures and the routines that
+manipulate them are discussed in detail in this section, while the
+interrupt level context structure is discussed in the XXX.
+
+Additionally, if the GNU debugger gdb is to be made aware of RTEMS tasks
+for this CPU, then care should be used in designing the context area.
+
+@example
+typedef struct @{
+    unsigned32 special_interrupt_register;
+@} CPU_Interrupt_frame;
+@end example
+
+
+@subsection Basic Context Data Structure
+
+The Context_Control data structure contains the basic integer context of a
+task.  In addition, this context area contains stack and frame pointers,
+processor status register(s), and any other registers that are normally
+altered by compiler generated code.  In addition, this context must
+contain the processor interrupt level since the processor interrupt level
+is maintained on a per-task basis.  This is necessary to support the
+interrupt level portion of the task mode as provided by the Classic RTEMS
+API.
+
+On some processors, it is cost-effective to save only the callee preserved
+registers during a task context switch.  This means that the ISR code
+needs to save those registers which do not persist across function calls.  
+It is not mandatory to make this distinctions between the caller/callee
+saves registers for the purpose of minimizing context saved during task
+switch and on interrupts.  If the cost of saving extra registers is
+minimal, simplicity is the choice.  Save the same context on interrupt
+entry as for tasks in this case.
+
+The Context_Control data structure should be defined such that the order
+of elements results in the simplest, most efficient implementation of XXX.  
+A typical implementation starts with a definition such as the following:
+
+@example
+typedef struct @{
+    unsigned32 some_integer_register;
+    unsigned32 another_integer_register;
+    unsigned32 some_system_register;
+@} Context_Control;
+@end example
+
+@subsection Initializing a Context
+
+The _CPU_Context_Initialize routine initializes the context to a state
+suitable for starting a task after a context restore operation.  
+Generally, this involves:
+
+@itemize @bullet
+
+@item  setting a starting address,
+
+@item  preparing the stack,
+
+@item  preparing the stack and frame pointers,
+
+@item  setting the proper interrupt level in the context, and
+
+@item  initializing the floating point context
+
+@end itemize
+
+This routine generally does not set any unnecessary register in the
+context.  The state of the "general data" registers is undefined at task
+start time. The _CPU_Context_initialize routine is prototyped as follows:
+
+@example
+void _CPU_Context_Initialize( 
+    Context_Control *_the_context,
+    void            *_stack_base, 
+    unsigned32       _size,
+    unsigned32       _isr,
+    void            *_entry_point,
+    unsigned32       _is_fp
+);
+@end example
+
+This is_fp parameter is TRUE if the thread is to be a floating point
+thread.  This is typically only used on CPUs where the FPU may be easily
+disabled by software such as on the SPARC where the PSR contains an enable
+FPU bit.  The use of an FPU enable bit allows RTEMS to ensure that a
+non-floating point task is unable to access the FPU.  This guarantees that
+a deferred floating point context switch is safe.
+
+XXX explain other parameters and check prototype
+
+@subsection Performing a Context Switch
+
+The _CPU_Context_switch performs a normal non-FP context switch from the
+context of the current executing thread to the context of the heir thread.
+
+@example
+void _CPU_Context_switch(
+  Context_Control  *run,
+  Context_Control  *heir
+);
+@end example
+
+@subsection Restoring a Context
+
+The _CPU_Context_restore routine is generally used only to restart the
+currently executing thread (i.e. self) in an efficient manner.  In many
+ports, it can simply be a label in _CPU_Context_switch. It may be
+unnecessary to reload some registers.
+
+@example
+void _CPU_Context_restore(
+  Context_Control *new_context
+);
+@end example
+
+@subsection Restarting the Currently Executing Task
+
+The _CPU_Context_Restart_self is responsible for somehow restarting the
+currently executing task.  If you are lucky when porting RTEMS, then all
+that is necessary is restoring the context.  Otherwise, there will need to
+be a routine that does something special in this case.  Performing a
+_CPU_Context_Restore on the currently executing task after reinitializing
+that context should work on most ports.  It will not work if restarting
+self conflicts with the stack frame assumptions of restoring a context.
+
+The following is an implementation of _CPU_Context_Restart_self that can
+be used when no special handling is required for this case.
+
+@example
+#define _CPU_Context_Restart_self( _the_context ) \
+   _CPU_Context_restore( (_the_context) )
+@end example
+
+XXX find a port which does not do it this way and include it here
+
+@section Floating Point Context
+
+@subsection CPU_HAS_FPU Macro Definition
+
+The CPU_HAS_FPU macro is set based on the answer to the question: Does the
+CPU have hardware floating point?  If the CPU has an FPU, then this should
+be set to TRUE.  Otherwise, it should be set to FALSE.  The primary
+implication of setting this macro to TRUE is that it indicates that tasks
+may have floating point contexts.  In the Classic API, this means that the
+RTEMS_FLOATING_POINT task attribute specified as part of rtems_task_create
+is supported on this CPU.  If CPU_HAS_FPU is set to FALSE, then no tasks
+or threads may be floating point and the RTEMS_FLOATING_POINT task
+attribute is ignored.  On an API such as POSIX where all threads
+implicitly have a floating point context, then the setting of this macro
+determines whether every POSIX thread has a floating point context.
+
+The following example illustrates how the CPU_HARDWARE_FP (XXX macro name
+is varying) macro is set based on the CPU family dependent macro.
+
+@example
+#if ( THIS_CPU_FAMILY_HAS_FPU == 1 ) /* where THIS_CPU_FAMILY */
+                                     /* might be M68K */
+#define CPU_HARDWARE_FP     TRUE
+#else
+#define CPU_HARDWARE_FP     FALSE
+#endif
+@end example
+
+The macro name THIS_CPU_FAMILY_HAS_FPU should be made CPU specific.  It
+indicates whether or not this CPU model has FP support.  For example, the
+definition of the i386ex and i386sx CPU models would set I386_HAS_FPU to
+FALSE to indicate that these CPU models are i386's without an i387 and
+wish to leave floating point support out of RTEMS when built for the
+i386_nofp processor model.  On a CPU with a built-in FPU like the i486,
+this would be defined as TRUE.
+
+On some processor families, the setting of the THIS_CPU_FAMILY_HAS_FPU
+macro may be derived from compiler predefinitions.  This can be used when
+the compiler distinguishes the individual CPU models for this CPU family
+as distinctly as RTEMS requires.  Often RTEMS needs to need more about the
+CPU model than the compiler because of differences at the system level
+such as caching, interrupt structure.
+
+@subsection CPU_ALL_TASKS_ARE_FP Macro Setting
+
+The CPU_ALL_TASKS_ARE_FP macro is set to TRUE or FALSE based upon the
+answer to the following question: Are all tasks RTEMS_FLOATING_POINT tasks
+implicitly?  If this macro is set TRUE, then all tasks and threads are
+assumed to have a floating point context.  In the Classic API, this is
+equivalent to setting the RTEMS_FLOATING_POINT task attribute on all
+rtems_task_create calls.  If the CPU_ALL_TASKS_ARE_FP macro is set to
+FALSE, then the RTEMS_FLOATING_POINT task attribute in the Classic API is
+honored.
+
+The rationale for this macro is that if a function that an application
+developer would not think utilize the FP unit DOES, then one can not
+easily predict which tasks will use the FP hardware. In this case, this
+option should be TRUE.  So far, the only CPU families for which this macro
+has been to TRUE are the HP PA-RISC and PowerPC.  For the HP PA-RISC, the
+HP C compiler and gcc both implicitly use the floating point registers to
+perform integer multiplies.  For the PowerPC, this feature macro is set to
+TRUE because the printf routine saves a floating point register whether or
+not a floating point number is actually printed.  If the newlib
+implementation of printf were restructured to avoid this, then the PowerPC
+port would not have to have this option set to TRUE.
+
+The following example illustrates how the CPU_ALL_TASKS_ARE_FP is set on
+the PowerPC.  On this CPU family, this macro is set to TRUE if the CPU
+model has hardware floating point.
+
+@example
+#if (CPU_HARDWARE_FP == TRUE)
+#define CPU_ALL_TASKS_ARE_FP     TRUE
+#else
+#define CPU_ALL_TASKS_ARE_FP     FALSE
+#endif
+@end example
+
+NOTE: If CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.
+
+@subsection CPU_USE_DEFERRED_FP_SWITCH Macro Setting
+
+The CPU_USE_DEFERRED_FP_SWITCH macro is set based upon the answer to the
+following question:  Should the saving of the floating point registers be
+deferred until a context switch is made to another different floating
+point task?  If the floating point context will not be stored until
+necessary, then this macro should be set to TRUE.  When set to TRUE, the
+floating point context of a task will remain in the floating point
+registers and not disturbed until another floating point task is switched
+to.
+
+If the CPU_USE_DEFERRED_FP_SWITCH is set to FALSE, then the floating point
+context is saved each time a floating point task is switched out and
+restored when the next floating point task is restored.  The state of the
+floating point registers between those two operations is not specified.
+
+There are a couple of known cases where the port should not defer saving
+the floating point context.  The first case is when the compiler generates
+instructions that use the FPU when floating point is not actually used.  
+This occurs on the HP PA-RISC for example when an integer multiply is
+performed.  On the PowerPC, the printf routine includes a save of a
+floating point register to support printing floating point numbers even if
+the path that actually prints the floating point number is not invoked.  
+In both of these cases, deferred floating point context switches can not
+be used.  If the floating point context has to be saved as part of
+interrupt dispatching, then it may also be necessary to disable deferred
+context switches.
+
+Setting this flag to TRUE results in using a different algorithm for
+deciding when to save and restore the floating point context.  The
+deferred FP switch algorithm minimizes the number of times the FP context
+is saved and restored.  The FP context is not saved until a context switch
+is made to another, different FP task.  Thus in a system with only one FP
+task, the FP context will never be saved or restored.
+
+The following illustrates setting the CPU_USE_DEFERRED_FP_SWITCH macro on
+a processor family such as the M68K or i386 which can use deferred
+floating point context switches.
+
+@example
+#define CPU_USE_DEFERRED_FP_SWITCH       TRUE
+@end example
+
+@subsection Floating Point Context Data Structure
+
+The Context_Control_fp contains the per task information for the floating
+point unit.  The organization of this structure may be a list of floating
+point registers along with any floating point control and status registers
+or it simply consist of an array of a fixed number of bytes.  Defining the
+floating point context area as an array of bytes is done when the floating
+point context is dumped by a "FP save context" type instruction and the
+format is either not completely defined by the CPU documentation or the
+format is not critical for the implementation of the floating point
+context switch routines.  In this case, there is no need to figure out the
+exact format -- only the size.  Of course, although this is enough
+information for RTEMS, it is probably not enough for a debugger such as
+gdb.  But that is another problem.
+
+@example
+typedef struct @{
+    double      some_float_register;
+@} Context_Control_fp;
+@end example
+
+
+On some CPUs with hardware floating point support, the Context_Control_fp
+structure will not be used.
+
+@subsection Size of Floating Point Context Macro
+
+The CPU_CONTEXT_FP_SIZE macro is set to the size of the floating point
+context area. On some CPUs this will not be a "sizeof" because the format
+of the floating point area is not defined -- only the size is.  This is
+usually on CPUs with a "floating point save context" instruction.  In
+general, though it is easier to define the structure as a "sizeof"
+operation and define the Context_Control_fp structure to be an area of
+bytes of the required size in this case.
+
+@example
+#define CPU_CONTEXT_FP_SIZE sizeof( Context_Control_fp )
+@end example
+
+@subsection Start of Floating Point Context Area Macro
+
+The _CPU_Context_Fp_start macro is used in the XXX routine and allows the initial pointer into a  floating point context area (used to save the floating point context) to be at an arbitrary place in the floating point context area.  This is necessary because some FP units are designed to have their context saved as a stack which grows into lower addresses.  Other FP units can be saved by simply moving registers into offsets from the base of the context area.  Finally some FP units provide a "dump context" instruction which could fill in from high to low or low to high based on the whim of the CPU designers.  Regardless, the address at which that floating point context area pointer should start within the actual floating point context area varies between ports and this macro provides a clean way of addressing this.
+
+This is a common implementation of the _CPU_Context_Fp_start routine which
+is suitable for many processors.  In particular, RISC processors tend to
+use this implementation since the floating point context is saved as a
+sequence of store operations.
+
+@example
+#define _CPU_Context_Fp_start( _base, _offset ) \
+   ( (void *) _Addresses_Add_offset( (_base), (_offset) ) )
+@end example
+
+In contrast, the m68k treats the floating point context area as a stack
+which grows downward in memory.  Thus the following implementation of
+_CPU_Context_Fp_start is used in that port:
+
+
+@example
+XXX insert m68k version here
+@end example
+
+@subsection Initializing a Floating Point Context
+
+The _CPU_Context_Initialize_fp routine initializes the floating point
+context area passed to it to. There are a few standard ways in which to
+initialize the floating point context.  The simplest, and least
+deterministic behaviorally, is to do nothing.  This leaves the FPU in a
+random state and is generally not a suitable way to implement this
+routine.  The second common implementation is to place a "null FP status
+word" into some status/control register in the FPU.  This mechanism is
+simple and works on many FPUs.  Another common way is to initialize the
+FPU to a known state during _CPU_Initialize and save the context (using
+_CPU_Context_save_fp_context) into the special floating point context
+_CPU_Null_fp_context.  Then all that is required to initialize a floating
+point context is to copy _CPU_Null_fp_context to the destination floating
+point context passed to it.  The following example implementation shows
+how to accomplish this:
+
+@example
+#define _CPU_Context_Initialize_fp( _destination ) \
+  @{ \
+   *((Context_Control_fp *) *((void **) _destination)) = _CPU_Null_fp_context; \
+  @}
+@end example
+
+The _CPU_Null_fp_context is optional.  A port need only include this variable when it uses the above mechanism to initialize a floating point context.  This is typically done on CPUs where it is difficult to generate an "uninitialized" FP context.  If the port requires this variable, then it is declared as follows:
+
+@example
+Context_Control_fp  _CPU_Null_fp_context;
+@end example
+
+
+@subsection Saving a Floating Point Context
+
+The _CPU_Context_save_fp_context routine is responsible for saving the FP
+context at *fp_context_ptr.  If the point to load the FP context from is
+changed then the pointer is modified by this routine.
+
+Sometimes a macro implementation of this is in cpu.h which dereferences
+the ** and a similarly named routine in this file is passed something like
+a (Context_Control_fp *).  The general rule on making this decision is to
+avoid writing assembly language.
+
+@example
+void _CPU_Context_save_fp(
+  void **fp_context_ptr
+)
+@end example
+
+@subsection Restoring a Floating Point Context
+
+The _CPU_Context_restore_fp_context is responsible for restoring the FP
+context at *fp_context_ptr.  If the point to load the FP context from is
+changed then the pointer is modified by this routine.
+
+Sometimes a macro implementation of this is in cpu.h which dereferences
+the ** and a similarly named routine in this file is passed something like
+a (Context_Control_fp *).  The general rule on making this decision is to
+avoid writing assembly language.
+
+@example
+void _CPU_Context_restore_fp(
+  void **fp_context_ptr
+);
+@end example
+