RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

2006-08-23 Joel Sherrill <joel@OARcorp.com>

Browse Source 
* Makefile.am, configure.ac, FAQ/stamp-vti, FAQ/version.texi,
	common/cpright.texi: Merging CPU Supplements into a single document.
	As part of this removed the obsolete and impossible to maintain size
	and timing information.
	* cpu_supplement/.cvsignore, cpu_supplement/Makefile.am,
	cpu_supplement/arm.t, cpu_supplement/i386.t, cpu_supplement/m68k.t,
	cpu_supplement/mips.t, cpu_supplement/powerpc.t,
	cpu_supplement/preface.texi, cpu_supplement/sh.t,
	cpu_supplement/sparc.t, cpu_supplement/tic4x.t: New files.
	* supplements/.cvsignore, supplements/Makefile.am,
	supplements/supplement.am, supplements/arm/.cvsignore,
	supplements/arm/BSP_TIMES, supplements/arm/ChangeLog,
	supplements/arm/Makefile.am, supplements/arm/arm.texi,
	supplements/arm/bsp.t, supplements/arm/callconv.t,
	supplements/arm/cpumodel.t, supplements/arm/cputable.t,
	supplements/arm/fatalerr.t, supplements/arm/intr_NOTIMES.t,
	supplements/arm/memmodel.t, supplements/arm/preface.texi,
	supplements/arm/timeBSP.t, supplements/c4x/.cvsignore,
	supplements/c4x/BSP_TIMES, supplements/c4x/ChangeLog,
	supplements/c4x/Makefile.am, supplements/c4x/bsp.t,
	supplements/c4x/c4x.texi, supplements/c4x/callconv.t,
	supplements/c4x/cpumodel.t, supplements/c4x/cputable.t,
	supplements/c4x/fatalerr.t, supplements/c4x/intr_NOTIMES.t,
	supplements/c4x/memmodel.t, supplements/c4x/preface.texi,
	supplements/c4x/timeBSP.t, supplements/i386/.cvsignore,
	supplements/i386/ChangeLog, supplements/i386/FORCE386_TIMES,
	supplements/i386/Makefile.am, supplements/i386/bsp.t,
	supplements/i386/callconv.t, supplements/i386/cpumodel.t,
	supplements/i386/cputable.t, supplements/i386/fatalerr.t,
	supplements/i386/i386.texi, supplements/i386/intr_NOTIMES.t,
	supplements/i386/memmodel.t, supplements/i386/preface.texi,
	supplements/i386/timeFORCE386.t, supplements/m68k/.cvsignore,
	supplements/m68k/ChangeLog, supplements/m68k/MVME136_TIMES,
	supplements/m68k/Makefile.am, supplements/m68k/bsp.t,
	supplements/m68k/callconv.t, supplements/m68k/cpumodel.t,
	supplements/m68k/cputable.t, supplements/m68k/fatalerr.t,
	supplements/m68k/intr_NOTIMES.t, supplements/m68k/m68k.texi,
	supplements/m68k/memmodel.t, supplements/m68k/preface.texi,
	supplements/m68k/timeMVME136.t, supplements/m68k/timedata.t,
	supplements/mips/.cvsignore, supplements/mips/BSP_TIMES,
	supplements/mips/ChangeLog, supplements/mips/Makefile.am,
	supplements/mips/bsp.t, supplements/mips/callconv.t,
	supplements/mips/cpumodel.t, supplements/mips/cputable.t,
	supplements/mips/fatalerr.t, supplements/mips/intr_NOTIMES.t,
	supplements/mips/memmodel.t, supplements/mips/mips.texi,
	supplements/mips/preface.texi, supplements/mips/timeBSP.t,
	supplements/powerpc/.cvsignore, supplements/powerpc/ChangeLog,
	supplements/powerpc/DMV177_TIMES, supplements/powerpc/Makefile.am,
	supplements/powerpc/PSIM_TIMES, supplements/powerpc/bsp.t,
	supplements/powerpc/callconv.t, supplements/powerpc/cpumodel.t,
	supplements/powerpc/cputable.t, supplements/powerpc/fatalerr.t,
	supplements/powerpc/intr_NOTIMES.t, supplements/powerpc/memmodel.t,
	supplements/powerpc/powerpc.texi, supplements/powerpc/preface.texi,
	supplements/powerpc/timeDMV177.t, supplements/powerpc/timePSIM.t,
	supplements/sh/.cvsignore, supplements/sh/BSP_TIMES,
	supplements/sh/ChangeLog, supplements/sh/Makefile.am,
	supplements/sh/bsp.t, supplements/sh/callconv.t,
	supplements/sh/cpumodel.t, supplements/sh/cputable.t,
	supplements/sh/fatalerr.t, supplements/sh/intr_NOTIMES.t,
	supplements/sh/memmodel.t, supplements/sh/preface.texi,
	supplements/sh/sh.texi, supplements/sh/timeBSP.t,
	supplements/sparc/.cvsignore, supplements/sparc/ChangeLog,
	supplements/sparc/ERC32_TIMES, supplements/sparc/Makefile.am,
	supplements/sparc/bsp.t, supplements/sparc/callconv.t,
	supplements/sparc/cpumodel.t, supplements/sparc/cputable.t,
	supplements/sparc/fatalerr.t, supplements/sparc/intr_NOTIMES.t,
	supplements/sparc/memmodel.t, supplements/sparc/preface.texi,
	supplements/sparc/sparc.texi, supplements/sparc/timeERC32.t,
	supplements/template/.cvsignore, supplements/template/BSP_TIMES,
	supplements/template/ChangeLog, supplements/template/Makefile.am,
	supplements/template/bsp.t, supplements/template/callconv.t,
	supplements/template/cpumodel.t, supplements/template/cputable.t,
	supplements/template/fatalerr.t, supplements/template/intr_NOTIMES.t,
	supplements/template/memmodel.t, supplements/template/preface.texi,
	supplements/template/template.texi, supplements/template/timeBSP.t: Removed.
This commit is contained in:
Joel Sherrill
2006-08-23 19:11:14 +00:00
parent e8beb87007
commit 83fb86f32b
149 changed files with 6702 additions and 13981 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
doc/cpu_supplement/.cvsignore Normal file
View File

@@ -0,0 +1,28 @@
cpu_supplement
cpu_supplement-?
cpu_supplement-??
cpu_supplement.aux
cpu_supplement.cp
cpu_supplement.cps
cpu_supplement.dvi
cpu_supplement.fn
cpu_supplement.fns
cpu_supplement*.html
cpu_supplement.ky
cpu_supplement.log
cpu_supplement.pdf
cpu_supplement.pg
cpu_supplement.ps
cpu_supplement.toc
cpu_supplement.tp
cpu_supplement.vr
index.html
Makefile
Makefile.in
mdate-sh
rtems_footer.html
rtems_header.html
rtemspie.pdf
stamp-vti
states.pdf
version.texi

81
doc/cpu_supplement/Makefile.am Normal file
View File

@@ -0,0 +1,81 @@
#
# COPYRIGHT (c) 1988-2002.
# On-Line Applications Research Corporation (OAR).
# All rights reserved.
#
# $Id$
#
PROJECT = cpu_supplement
EDITION = 1
include $(top_srcdir)/project.am
REPLACE2 = $(PERL) $(top_srcdir)/tools/word-replace2
html_projectdir = $(htmldir)/$(PROJECT)
TEXI2WWW_ARGS=\
-I $(srcdir) -I $(top_srcdir) -I $(top_builddir) \
-dirfile ../index.html \
-header rtems_header.html \
-footer rtems_footer.html \
-icons ../images
GENERATED_FILES = arm.texi i386.texi m68k.texi mips.texi powerpc.texi \
sh.texi sparc.texi tic4x.texi
COMMON_FILES += $(top_srcdir)/common/cpright.texi
FILES = preface.texi
info_TEXINFOS = cpu_supplement.texi
cpu_supplement_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)
#
# Chapters which get automatic processing
#
arm.texi: arm.t
$(BMENU2) -p "Preface" \
-u "Top" \
-n "" < $< > $@
i386.texi: i386.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
m68k.texi: m68k.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
mips.texi: mips.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
powerpc.texi: powerpc.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
sh.texi: sh.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
sparc.texi: sparc.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
tic4x.texi: tic4x.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
CLEANFILES += cpu_supplement.info
CLEANFILES += cpu_supplement.info-1
CLEANFILES += cpu_supplement.info-2

595
doc/cpu_supplement/arm.t Normal file
View File

@@ -0,0 +1,595 @@
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@ifinfo
@end ifinfo
@chapter ARM Specific Information
The Real Time Executive for Multiprocessor Systems (RTEMS)
is designed to be portable across multiple processor
architectures. However, the nature of real-time systems makes
it essential that the application designer understand certain
processor dependent implementation details. These processor
dependencies include calling convention, board support package
issues, interrupt processing, exact RTEMS memory requirements,
performance data, header files, and the assembly language
interface to the executive.
This document discusses the ARM architecture dependencies
in this port of RTEMS. The ARM family has a wide variety
of implementations by a wide range of vendors. Consequently,
there are 100's of CPU models within it.
It is highly recommended that the ARM
RTEMS application developer obtain and become familiar with the
documentation for the processor being used as well as the
documentation for the ARM architecture as a whole.
@subheading Architecture Documents
For information on the ARM architecture,
refer to the following documents available from Arm, Limited
(@file{http//www.arm.com/}). There does not appear to
be an electronic version of a manual on the architecture
in general on that site. The following book is a good
resource:
@itemize @bullet
@item @cite{David Seal. "ARM Architecture Reference Manual."
Addison-Wesley. @b{ISBN 0-201-73719-1}. 2001.}
@end itemize
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section CPU Model Dependent Features
Microprocessors are generally classified into
families with a variety of CPU models or implementations within
that family. Within a processor family, there is a high level
of binary compatibility. This family may be based on either an
architectural specification or on maintaining compatibility with
a popular processor. Recent microprocessor families such as the
ARM, SPARC, and PowerPC are based on an architectural specification
which is independent or any particular CPU model or
implementation. Older families such as the M68xxx and the iX86
evolved as the manufacturer strived to produce higher
performance processor models which maintained binary
compatibility with older models.
RTEMS takes advantage of the similarity of the
various models within a CPU family. Although the models do vary
in significant ways, the high level of compatibility makes it
possible to share the bulk of the CPU dependent executive code
across the entire family. Each processor family supported by
RTEMS has a list of features which vary between CPU models
within a family. For example, the most common model dependent
feature regardless of CPU family is the presence or absence of a
floating point unit or coprocessor. When defining the list of
features present on a particular CPU model, one simply notes
that floating point hardware is or is not present and defines a
single constant appropriately. Conditional compilation is
utilized to include the appropriate source code for this CPU
model's feature set. It is important to note that this means
that RTEMS is thus compiled using the appropriate feature set
and compilation flags optimal for this CPU model used. The
alternative would be to generate a binary which would execute on
all family members using only the features which were always
present.
This chapter presents the set of features which vary
across ARM implementations and are of importance to RTEMS.
The set of CPU model feature macros are defined in the file
cpukit/score/cpu/arm/rtems/score/arm.h based upon the particular CPU
model defined on the compilation command line.
@subsection CPU Model Name
The macro @code{CPU_MODEL_NAME} is a string which designates
the architectural level of this CPU model. The following is
a list of the settings for this string based upon @code{gcc}
CPU model predefines:
@example
__ARM_ARCH4__ "ARMv4"
__ARM_ARCH4T__ "ARMv4T"
__ARM_ARCH5__ "ARMv5"
__ARM_ARCH5T__ "ARMv5T"
__ARM_ARCH5E__ "ARMv5E"
__ARM_ARCH5TE__ "ARMv5TE"
@end example
@subsection Count Leading Zeroes Instruction
The ARMv5 and later has the count leading zeroes (@code{clz})
instruction which could be used to speed up the find first bit
operation. The use of this instruction should significantly speed up
the scheduling associated with a thread blocking.
@subsection Floating Point Unit
The macro ARM_HAS_FPU is set to 1 to indicate that
this CPU model has a hardware floating point unit and 0
otherwise. It does not matter whether the hardware floating
point support is incorporated on-chip or is an external
coprocessor.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Calling Conventions
Each high-level language compiler generates
subroutine entry and exit code based upon a set of rules known
as the compiler's calling convention. These rules address the
following issues:
@itemize @bullet
@item register preservation and usage
@item parameter passing
@item call and return mechanism
@end itemize
A compiler's calling convention is of importance when
interfacing to subroutines written in another language either
assembly or high-level. Even when the high-level language and
target processor are the same, different compilers may use
different calling conventions. As a result, calling conventions
are both processor and compiler dependent.
@subsection Processor Background
The ARM architecture supports a simple yet
effective call and return mechanism. A subroutine is invoked
via the branch and link (@code{bl}) instruction. This instruction
saves the return address in the @code{lr} register. Returning
from a subroutine only requires that the return address be
moved into the program counter (@code{pc}), possibly with
an offset. It is is important to
note that the @code{bl} instruction 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.
@subsection Calling Mechanism
All RTEMS directives are invoked using the @code{bl}
instruction and return to the user application via the
mechanism described above.
@subsection Register Usage
As discussed above, the ARM's call and return mechanism dos
not automatically save any registers. RTEMS uses the registers
@code{r0}, @code{r1}, @code{r2}, and @code{r3} as scratch registers and
per ARM calling convention, the @code{lr} register is altered
as well. These registers are not preserved by RTEMS directives
therefore, the contents of these registers should not be assumed
upon return from any RTEMS directive.
@subsection Parameter Passing
RTEMS assumes that ARM calling conventions are followed and that
the first four arguments are placed in registers @code{r0} through
@code{r3}. If there are more arguments, than that, then they
are place on the stack.
@subsection User-Provided Routines
All user-provided routines invoked by RTEMS, such as
user extensions, device drivers, and MPCI routines, must also
adhere to these calling conventions.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Memory Model
A processor may support any combination of memory
models ranging from pure physical addressing to complex demand
paged virtual memory systems. RTEMS supports a flat memory
model which ranges contiguously over the processor's allowable
address space. RTEMS does not support segmentation or virtual
memory of any kind. The appropriate memory model for RTEMS
provided by the targeted processor and related characteristics
of that model are described in this chapter.
@subsection Flat Memory Model
Members of the ARM family newer than Version 3 support 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 the endian
mode that the processor is configured for. In general, ARM
processors are used in little endian mode.
Some of the ARM family members such as the
920 and 720 include an MMU and thus support virtual memory and
segmentation. RTEMS does not support virtual memory or
segmentation on any of the ARM family members.
@c
@c Interrupt Stack Frame Picture
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Interrupt Processing
Different types of processors respond to the
occurrence of an interrupt in its own unique fashion. In
addition, each processor type provides a control mechanism to
allow for the proper handling of an interrupt. The processor
dependent response to the interrupt modifies the current
execution state and results in a change in the execution stream.
Most processors require that an interrupt handler utilize some
special control mechanisms to return to the normal processing
stream. Although RTEMS hides many of the processor dependent
details of interrupt processing, it is important to understand
how the RTEMS interrupt manager is mapped onto the processor's
unique architecture. Discussed in this chapter are the ARM's
interrupt response and control mechanisms as they pertain to
RTEMS.
The ARM has 7 exception types:
@itemize @bullet
@item Reset
@item Undefined instruction
@item Software interrupt (SWI)
@item Prefetch Abort
@item Data Abort
@item Interrupt (IRQ)
@item Fast Interrupt (FIQ)
@end itemize
Of these types, only IRQ and FIQ are handled through RTEMS's interrupt
vectoring.
@subsection Vectoring of an Interrupt Handler
Unlike many other architectures, the ARM has seperate stacks for each
interrupt. When the CPU receives an interrupt, it:
@itemize @bullet
@item switches to the exception mode corresponding to the interrupt,
@item saves the Current Processor Status Register (CPSR) to the
exception mode's Saved Processor Status Register (SPSR),
@item masks off the IRQ and if the interrupt source was FIQ, the FIQ
is masked off as well,
@item saves the Program Counter (PC) to the exception mode's Link
Register (LR - same as R14),
@item and sets the PC to the exception's vector address.
@end itemize
The vectors for both IRQ and FIQ point to the _ISR_Handler function.
_ISR_Handler() calls the BSP specific handler, ExecuteITHandler(). Before
calling ExecuteITHandler(), registers R0-R3, R12, and R14(LR) are saved so
that it is safe to call C functions. Even ExecuteITHandler() can be written
in C.
@subsection Interrupt Levels
The ARM architecture supports two external interrupts - IRQ and FIQ. FIQ
has a higher priority than IRQ, and has its own version of register R8 - R14,
however RTEMS does not take advantage of them. Both interrupts are enabled
through the CPSR.
The RTEMS interrupt level mapping scheme for the AEM is not a numeric level
as on most RTEMS ports. It is a bit mapping that corresponds the enable
bits's postions in the CPSR:
@table @b
@item FIQ
Setting bit 6 (0 is least significant bit) disables the FIQ.
@item IRQ
Setting bit 7 (0 is least significant bit) disables the IRQ.
@end table
@subsection Disabling of Interrupts by RTEMS
During the execution of directive calls, critical
sections of code may be executed. When these sections are
encountered, RTEMS disables interrupts to level seven (7) before
the execution of this section and restores them to the previous
level upon completion of the section. RTEMS has been optimized
to insure that interrupts are disabled for less than
RTEMS_MAXIMUM_DISABLE_PERIOD microseconds on a
RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ Mhz processor with
zero wait states. These numbers will vary based the
number of wait states and processor speed present on the target board.
[NOTE: The maximum period with interrupts disabled is hand calculated. This
calculation was last performed for Release
RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.]
Non-maskable interrupts (NMI) cannot be disabled, and
ISRs which execute at this level MUST NEVER issue RTEMS system
calls. If a directive is invoked, unpredictable results may
occur due to the inability of RTEMS to protect its critical
sections. However, ISRs that make no system calls may safely
execute as non-maskable interrupts.
@subsection Interrupt Stack
RTEMS expects the interrupt stacks to be set up in bsp_start(). The memory
for the stacks is reserved in the linker script.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Default Fatal Error Processing
Upon detection of a fatal error by either the
application or RTEMS the fatal error manager is invoked. The
fatal error manager will invoke the user-supplied fatal error
handlers. If no user-supplied handlers are configured, the
RTEMS provided default fatal error handler is invoked. If the
user-supplied fatal error handlers return to the executive the
default fatal error handler is then invoked. This chapter
describes the precise operations of the default fatal error
handler.
@subsection Default Fatal Error Handler Operations
The default fatal error handler which is invoked by
the @code{rtems_fatal_error_occurred} directive when there is
no user handler configured or the user handler returns control to
RTEMS. The default fatal error handler performs the
following actions:
@itemize @bullet
@item disables processor interrupts,
@item places the error code in @b{r0}, and
@item executes an infinite loop (@code{while(0);} to
simulate a halt processor instruction.
@end itemize
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Board Support Packages
An RTEMS Board Support Package (BSP) must be designed
to support a particular processor and target board combination.
This chapter presents a discussion of XXX specific BSP
issues. For more information on developing a BSP, refer to the
chapter titled Board Support Packages in the RTEMS
Applications User's Guide.
@subsection System Reset
An RTEMS based application is initiated or
re-initiated when the XXX processor is reset. When the
XXX is reset, the processor performs the following actions:
@itemize @bullet
@item The tracing bits of the status register are cleared to
disable tracing.
@item The supervisor interrupt state is entered by setting the
supervisor (S) bit and clearing the master/interrupt (M) bit of
the status register.
@item The interrupt mask of the status register is set to
level 7 to effectively disable all maskable interrupts.
@item The vector base register (VBR) is set to zero.
@item The cache control register (CACR) is set to zero to
disable and freeze the processor cache.
@item The interrupt stack pointer (ISP) is set to the value
stored at vector 0 (bytes 0-3) of the exception vector table
(EVT).
@item The program counter (PC) is set to the value stored at
vector 1 (bytes 4-7) of the EVT.
@item The processor begins execution at the address stored in
the PC.
@end itemize
@subsection 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 XXX's VBR value. Because interrupts
are enabled automatically by RTEMS as part of the initialize
executive directive, the VBR MUST be set before this directive
is invoked to insure 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 XXX version has the following
specific requirements:
@itemize @bullet
@item Must leave the S bit of the status register set so that
the XXX remains in the supervisor state.
@item Must set the M bit of the status register to remove the
XXX from the interrupt state.
@item 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.
@item Must initialize the XXX's vector table.
@end itemize
Note that the BSP is not responsible for allocating
or installing the interrupt stack. RTEMS does this
automatically as part of initialization. If the BSP does not
install an interrupt stack and -- for whatever reason -- an
interrupt occurs before initialize_executive is invoked, then
the results are unpredictable.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Processor Dependent Information Table
Any highly processor dependent information required
to describe a processor to RTEMS is provided in the CPU
Dependent Information Table. This table is not required for all
processors supported by RTEMS. This chapter describes the
contents, if any, for a particular processor type.
@subsection CPU Dependent Information Table
The XXX version of the RTEMS CPU Dependent
Information Table contains the information required to interface
a Board Support Package and RTEMS on the XXX. This
information is provided to allow RTEMS to interoperate
effectively with the BSP. The C structure definition is given
here:
@example
@group
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 */
/* XXX CPU family dependent stuff */
@} rtems_cpu_table;
@end group
@end example
@table @code
@item pretasking_hook
is the address of the user provided routine which is invoked
once RTEMS APIs are initialized. This routine will be invoked
before any system tasks are created. Interrupts are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item predriver_hook
is the address of the user provided
routine that is invoked immediately before the
the device drivers and MPCI are initialized. RTEMS
initialization is complete but interrupts and tasking are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item postdriver_hook
is the address of the user provided
routine that is invoked immediately after the
the device drivers and MPCI are initialized. RTEMS
initialization is complete but interrupts and tasking are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item idle_task
is the address of the optional user
provided routine which is used as the system's IDLE task. If
this field is not NULL, then the RTEMS default IDLE task is not
used. This field may be NULL to indicate that the default IDLE
is to be used.
@item do_zero_of_workspace
indicates whether RTEMS should
zero the Workspace as part of its initialization. If set to
TRUE, the Workspace is zeroed. Otherwise, it is not.
@item idle_task_stack_size
is the size of the RTEMS idle task stack in bytes.
If this number is less than MINIMUM_STACK_SIZE, then the
idle task's stack will be MINIMUM_STACK_SIZE in byte.
@item interrupt_stack_size
is the size of the RTEMS
allocated interrupt stack in bytes. This value must be at least
as large as MINIMUM_STACK_SIZE.
@item extra_mpci_receive_server_stack
is the extra stack space allocated for the RTEMS MPCI receive server task
in bytes. The MPCI receive server may invoke nearly all directives and
may require extra stack space on some targets.
@item stack_allocate_hook
is the address of the optional user provided routine which allocates
memory for task stacks. If this hook is not NULL, then a stack_free_hook
must be provided as well.
@item stack_free_hook
is the address of the optional user provided routine which frees
memory for task stacks. If this hook is not NULL, then a stack_allocate_hook
must be provided as well.
@item XXX
is where the CPU family dependent stuff goes.
@end table

694
doc/cpu_supplement/i386.t Normal file
View File

@@ -0,0 +1,694 @@
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@ifinfo
@end ifinfo
@chapter Intel/AMD x86 Specific Information
The Real Time Executive for Multiprocessor Systems
(RTEMS) is designed to be portable across multiple processor
architectures. However, the nature of real-time systems makes
it essential that the application designer understand certain
processor dependent implementation details. These processor
dependencies include calling convention, board support package
issues, interrupt processing, exact RTEMS memory requirements,
performance data, header files, and the assembly language
interface to the executive.
For information on the i386 processor, refer to the
following documents:
@itemize @bullet
@item @cite{386 Programmer's Reference Manual, Intel, Order No. 230985-002}.
@item @cite{386 Microprocessor Hardware Reference Manual, Intel,
Order No. 231732-003}.
@item @cite{80386 System Software Writer's Guide, Intel, Order No. 231499-001}.
@item @cite{80387 Programmer's Reference Manual, Intel, Order No. 231917-001}.
@end itemize
It is highly recommended that the i386 RTEMS
application developer obtain and become familiar with Intel's
386 Programmer's Reference Manual.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section CPU Model Dependent Features
Microprocessors are generally classified into
families with a variety of CPU models or implementations within
that family. Within a processor family, there is a high level
of binary compatibility. This family may be based on either an
architectural specification or on maintaining compatibility with
a popular processor. Recent microprocessor families such as the
SPARC or PowerPC are based on an architectural specification
which is independent or any particular CPU model or
implementation. Older families such as the M68xxx and the iX86
evolved as the manufacturer strived to produce higher
performance processor models which maintained binary
compatibility with older models.
RTEMS takes advantage of the similarity of the
various models within a CPU family. Although the models do vary
in significant ways, the high level of compatibility makes it
possible to share the bulk of the CPU dependent executive code
across the entire family. Each processor family supported by
RTEMS has a list of features which vary between CPU models
within a family. For example, the most common model dependent
feature regardless of CPU family is the presence or absence of a
floating point unit or coprocessor. When defining the list of
features present on a particular CPU model, one simply notes
that floating point hardware is or is not present and defines a
single constant appropriately. Conditional compilation is
utilized to include the appropriate source code for this CPU
model's feature set. It is important to note that this means
that RTEMS is thus compiled using the appropriate feature set
and compilation flags optimal for this CPU model used. The
alternative would be to generate a binary which would execute on
all family members using only the features which were always
present.
This chapter presents the set of features which vary
across i386 implementations and are of importance to RTEMS.
The set of CPU model feature macros are defined in the file
cpukit/score/cpu/i386/i386.h based upon the particular CPU
model defined on the compilation command line.
@subsection CPU Model Name
The macro CPU_MODEL_NAME is a string which designates
the name of this CPU model. For example, for the Intel i386 without an
i387 coprocessor, this macro is set to the string "i386 with i387".
@subsection bswap Instruction
The macro I386_HAS_BSWAP is set to 1 to indicate that
this CPU model has the @code{bswap} instruction which
endian swaps a thirty-two bit quantity. This instruction
appears to be present in all CPU models
i486's and above.
@subsection Floating Point Unit
The macro I386_HAS_FPU is set to 1 to indicate that
this CPU model has a hardware floating point unit and 0
otherwise. The hardware floating point may be on-chip (as in the
case of an i486DX or Pentium) or as a coprocessor (as in the case of
an i386/i387 combination).
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Calling Conventions
Each high-level language compiler generates
subroutine entry and exit code based upon a set of rules known
as the compiler's calling convention. These rules address the
following issues:
@itemize @bullet
@item register preservation and usage
@item parameter passing
@item call and return mechanism
@end itemize
A compiler's calling convention is of importance when
interfacing to subroutines written in another language either
assembly or high-level. Even when the high-level language and
target processor are the same, different compilers may use
different calling conventions. As a result, calling conventions
are both processor and compiler dependent.
@subsection Processor Background
The i386 architecture supports a simple yet effective
call and return mechanism. A subroutine is invoked via the call
(call) instruction. This instruction pushes the return address
on the stack. The return from subroutine (ret) instruction pops
the return address off the current stack and transfers control
to that instruction. It is is important to note that the i386
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.
@subsection Calling Mechanism
All RTEMS directives are invoked using a call
instruction and return to the user application via the ret
instruction.
@subsection Register Usage
As discussed above, the call instruction does not
automatically save any registers. RTEMS uses the registers EAX,
ECX, and EDX 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.
@subsection Parameter Passing
RTEMS assumes that arguments are placed on the
current stack before the directive is invoked via the call
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:
@example
push third argument
push second argument
push first argument
invoke directive
remove arguments from the stack
@end example
The arguments to RTEMS are typically pushed onto the
stack using a push instruction. 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 stack pointer.
@subsection User-Provided Routines
All user-provided routines invoked by RTEMS, such as
user extensions, device drivers, and MPCI routines, must also
adhere to these calling conventions.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Memory Model
A processor may support any combination of memory
models ranging from pure physical addressing to complex demand
paged virtual memory systems. RTEMS supports a flat memory
model which ranges contiguously over the processor's allowable
address space. RTEMS does not support segmentation or virtual
memory of any kind. The appropriate memory model for RTEMS
provided by the targeted processor and related characteristics
of that model are described in this chapter.
@subsection Flat Memory Model
RTEMS supports the i386 protected mode, flat memory
model with paging disabled. In this mode, the i386
automatically converts every address from a logical to a
physical address each time it is used. The i386 uses
information provided in the segment registers and the Global
Descriptor Table to convert these addresses. RTEMS assumes the
existence of the following segments:
@itemize @bullet
@item a single code segment at protection level (0) which
contains all application and executive code.
@item a single data segment at protection level zero (0) which
contains all application and executive data.
@end itemize
The i386 segment registers and associated selectors
must be initialized when the initialize_executive directive is
invoked. RTEMS treats the segment registers as system registers
and does not modify or context switch them.
This i386 memory model 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, half-word (2-bytes), or word (4 bytes).
RTEMS does not require that logical addresses map
directly to physical addresses, although it is desirable in many
applications to do so. If logical and physical addresses are
not the same, then an additional selector will be required so
RTEMS can access the Interrupt Descriptor Table to install
interrupt service routines. The selector number of this segment
is provided to RTEMS in the CPU Dependent Information Table.
By not requiring that logical addresses map directly
to physical addresses, the memory space of an RTEMS application
can be separated from that of a ROM monitor. For example, on
the Force Computers CPU386, the ROM monitor loads application
programs into a logical address space where logical address
0x00000000 corresponds to physical address 0x0002000. On this
board, RTEMS and the application use virtual addresses which do
not map to physical addresses.
RTEMS assumes that the DS and ES registers contain
the selector for the single data segment when a directive is
invoked. This assumption is especially important when
developing interrupt service routines.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Interrupt Processing
Different types of processors respond to the
occurrence of an interrupt in their own unique fashion. In
addition, each processor type provides a control mechanism to
allow the proper handling of an interrupt. The processor
dependent response to the interrupt modifies the execution state
and results in the modification of the execution stream. This
modification usually requires that an interrupt handler utilize
the provided control mechanisms to return to the normal
processing stream. Although RTEMS hides many of the processor
dependent details of interrupt processing, it is important to
understand how the RTEMS interrupt manager is mapped onto the
processor's unique architecture. Discussed in this chapter are
the the processor's response and control mechanisms as they
pertain to RTEMS.
@subsection Vectoring of Interrupt Handler
Although the i386 supports multiple privilege levels,
RTEMS and all user software executes at privilege level 0. This
decision was made by the RTEMS designers to enhance
compatibility with processors which do not provide sophisticated
protection facilities like those of the i386. This decision
greatly simplifies the discussion of i386 processing, as one
need only consider interrupts without privilege transitions.
Upon receipt of an interrupt the i386 automatically
performs the following actions:
@itemize @bullet
@item pushes the EFLAGS register
@item pushes the far address of the interrupted instruction
@item vectors to the interrupt service routine (ISR).
@end itemize
A nested interrupt is processed similarly by the
i386.
@subsection Interrupt Stack Frame
The structure of the Interrupt Stack Frame for the
i386 which is placed on the interrupt stack by the processor in
response to an interrupt is as follows:
@ifset use-ascii
@example
@group
+----------------------+
| Old EFLAGS Register | ESP+8
+----------+-----------+
| UNUSED | Old CS | ESP+4
+----------+-----------+
| Old EIP | ESP
+----------------------+
@end group
@end example
@end ifset
@ifset use-tex
@sp 1
@tex
\centerline{\vbox{\offinterlineskip\halign{
\strut\vrule#&
\hbox to 1.00in{\enskip\hfil#\hfil}&
\vrule#&
\hbox to 1.00in{\enskip\hfil#\hfil}&
\vrule#&
\hbox to 0.75in{\enskip\hfil#\hfil}
\cr
\multispan{4}\hrulefill\cr
& \multispan{3} Old EFLAGS Register\quad&&ESP+8\cr
\multispan{4}\hrulefill\cr
&UNUSED &&Old CS &&ESP+4\cr
\multispan{4}\hrulefill\cr
& \multispan{3} Old EIP && ESP\cr
\multispan{4}\hrulefill\cr
}}\hfil}
@end tex
@end ifset
@ifset use-html
@html
<CENTER>
<TABLE COLS=3 WIDTH="40%" BORDER=2>
<TR><TD ALIGN=center COLSPAN=2><STRONG>Old EFLAGS Register</STRONG></TD>
<TD ALIGN=center>0x0</TD></TR>
<TR><TD ALIGN=center><STRONG>UNUSED</STRONG></TD>
<TD ALIGN=center><STRONG>Old CS</STRONG></TD>
<TD ALIGN=center>0x2</TD></TR>
<TR><TD ALIGN=center COLSPAN=2><STRONG>Old EIP</STRONG></TD>
<TD ALIGN=center>0x4</TD></TR>
</TABLE>
</CENTER>
@end html
@end ifset
@subsection Interrupt Levels
Although RTEMS supports 256 interrupt levels, the
i386 only supports two -- enabled and disabled. Interrupts are
enabled when the interrupt-enable flag (IF) in the extended
flags (EFLAGS) is set. Conversely, interrupt processing is
inhibited when the IF is cleared. During a non-maskable
interrupt, all other interrupts, including other non-maskable
ones, are inhibited.
RTEMS interrupt levels 0 and 1 such that level zero
(0) indicates that interrupts are fully enabled and level one
that interrupts are disabled. All other RTEMS interrupt levels
are undefined and their behavior is unpredictable.
@subsection Disabling of Interrupts by RTEMS
During the execution of directive calls, critical
sections of code may be executed. When these sections are
encountered, RTEMS disables interrupts before the execution of
this section and restores them to the previous level upon
completion of the section. RTEMS has been optimized to insure
that interrupts are disabled for less than RTEMS_MAXIMUM_DISABLE_PERIOD
microseconds on a RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ Mhz i386 with zero
wait states. These numbers will vary based the number of wait states
and processor speed present on the target board. [NOTE: The maximum
period with interrupts disabled within RTEMS was last calculated for
Release RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.]
Non-maskable interrupts (NMI) cannot be disabled, and
ISRs which execute at this level MUST NEVER issue RTEMS system
calls. If a directive is invoked, unpredictable results may
occur due to the inability of RTEMS to protect its critical
sections. However, ISRs that make no system calls may safely
execute as non-maskable interrupts.
@subsection Interrupt Stack
The i386 family does not support a dedicated hardware
interrupt stack. On this processor, RTEMS allocates and manages
a dedicated interrupt stack. As part of vectoring a non-nested
interrupt service routine, RTEMS switches from the stack of the
interrupted task to a dedicated interrupt stack. When a
non-nested interrupt returns, RTEMS switches back to the stack
of the interrupted stack. The current stack pointer is not
altered by RTEMS on nested interrupt.
Without a dedicated interrupt stack, every task in
the system MUST have enough stack space to accommodate the worst
case stack usage of that particular task and the interrupt
service routines COMBINED. By supporting a dedicated interrupt
stack, RTEMS significantly lowers the stack requirements for
each task.
RTEMS allocates the dedicated interrupt stack from
the Workspace Area. The amount of memory allocated for the
interrupt stack is determined by the interrupt_stack_size field
in the CPU Configuration Table.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Default Fatal Error Processing
Upon detection of a fatal error by either the
application or RTEMS the fatal error manager is invoked. The
fatal error manager will invoke the user-supplied fatal error
handlers. If no user-supplied handlers are configured, the
RTEMS provided default fatal error handler is invoked. If the
user-supplied fatal error handlers return to the executive the
default fatal error handler is then invoked. This chapter
describes the precise operations of the default fatal error
handler.
@subsection Default Fatal Error Handler Operations
The default fatal error handler which is invoked by
the fatal_error_occurred directive when there is no user handler
configured or the user handler returns control to RTEMS. The
default fatal error handler disables processor interrupts,
places the error code in EAX, and executes a HLT instruction to
halt the processor.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Board Support Packages
An RTEMS Board Support Package (BSP) must be designed to support a
particular processor and target board combination. This chapter presents a
discussion of i386 specific BSP issues. For more information on developing
a BSP, refer to the chapter titled Board Support Packages in the RTEMS
Applications User's Guide.
@subsection System Reset
An RTEMS based application is initiated when the i386
processor is reset. When the i386 is reset,
@itemize @bullet
@item The EAX register is set to indicate the results of the processor's
power-up self test. If the self-test was not executed, the contents of
this register are undefined. Otherwise, a non-zero value indicates the
processor is faulty and a zero value indicates a successful self-test.
@item The DX register holds a component identifier and revision level. DH
contains 3 to indicate an i386 component and DL contains a unique revision
level indicator.
@item Control register zero (CR0) is set such that the processor is in real
mode with paging disabled. Other portions of CR0 are used to indicate the
presence of a numeric coprocessor.
@item All bits in the extended flags register (EFLAG) which are not
permanently set are cleared. This inhibits all maskable interrupts.
@item The Interrupt Descriptor Register (IDTR) is set to point at address
zero.
@item All segment registers are set to zero.
@item The instruction pointer is set to 0x0000FFF0. The first instruction
executed after a reset is actually at 0xFFFFFFF0 because the i386 asserts
the upper twelve address until the first intersegment (FAR) JMP or CALL
instruction. When a JMP or CALL is executed, the upper twelve address
lines are lowered and the processor begins executing in the first megabyte
of memory.
@end itemize
Typically, an intersegment JMP to the application's initialization code is
placed at address 0xFFFFFFF0.
@subsection Processor Initialization
This initialization code is responsible for initializing all data
structures required by the i386 in protected mode and for actually entering
protected mode. The i386 must be placed in protected mode and the segment
registers and associated selectors must be initialized before the
initialize_executive directive is invoked.
The initialization code is responsible for initializing the Global
Descriptor Table such that the i386 is in the thirty-two bit flat memory
model with paging disabled. In this mode, the i386 automatically converts
every address from a logical to a physical address each time it is used.
For more information on the memory model used by RTEMS, please refer to the
Memory Model chapter in this document.
Since the processor is in real mode upon reset, the processor must be
switched to protected mode before RTEMS can execute. Before switching to
protected mode, at least one descriptor table and two descriptors must be
created. Descriptors are needed for a code segment and a data segment. (
This will give you the flat memory model.) The stack can be placed in a
normal read/write data segment, so no descriptor for the stack is needed.
Before the GDT can be used, the base address and limit must be loaded into
the GDTR register using an LGDT instruction.
If the hardware allows an NMI to be generated, you need to create the IDT
and a gate for the NMI interrupt handler. Before the IDT can be used, the
base address and limit for the idt must be loaded into the IDTR register
using an LIDT instruction.
Protected mode is entered by setting thye PE bit in the CR0 register.
Either a LMSW or MOV CR0 instruction may be used to set this bit. Because
the processor overlaps the interpretation of several instructions, it is
necessary to discard the instructions from the read-ahead cache. A JMP
instruction immediately after the LMSW changes the flow and empties the
processor if intructions which have been pre-fetched and/or decoded. At
this point, the processor is in protected mode and begins to perform
protected mode application initialization.
If the application requires that the IDTR be some value besides zero, then
it should set it to the required value at this point. All tasks share the
same i386 IDTR value. Because interrupts are enabled automatically by
RTEMS as part of the initialize_executive directive, the IDTR MUST be set
properly before this directive is invoked to insure correct interrupt
vectoring. If processor caching is to be utilized, then it should be
enabled during the reset application initialization code. The reset code
which is executed before the call to initialize_executive has the following
requirements:
For more information regarding the i386s data structures and their
contents, refer to Intel's 386 Programmer's Reference Manual.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Processor Dependent Information Table
Any highly processor dependent information required
to describe a processor to RTEMS is provided in the CPU
Dependent Information Table. This table is not required for all
processors supported by RTEMS. This chapter describes the
contents, if any, for a particular processor type.
@subsection CPU Dependent Information Table
The i386 version of the RTEMS CPU Dependent
Information Table contains the information required to interface
a Board Support Package and RTEMS on the i386. This information
is provided to allow RTEMS to interoperate effectively with the
BSP. The C structure definition is given here:
@example
@group
typedef struct @{
void (*pretasking_hook)( void );
void (*predriver_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 interrupt_segment;
void *interrupt_vector_table;
@} rtems_cpu_table;
@end group
@end example
@table @code
@item pretasking_hook
is the address of the user provided routine which is invoked
once RTEMS APIs are initialized. This routine will be invoked
before any system tasks are created. Interrupts are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item predriver_hook
is the address of the user provided
routine that is invoked immediately before the
the device drivers and MPCI are initialized. RTEMS
initialization is complete but interrupts and tasking are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item postdriver_hook
is the address of the user provided
routine that is invoked immediately after the
the device drivers and MPCI are initialized. RTEMS
initialization is complete but interrupts and tasking are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item idle_task
is the address of the optional user
provided routine which is used as the system's IDLE task. If
this field is not NULL, then the RTEMS default IDLE task is not
used. This field may be NULL to indicate that the default IDLE
is to be used.
@item do_zero_of_workspace
indicates whether RTEMS should
zero the Workspace as part of its initialization. If set to
TRUE, the Workspace is zeroed. Otherwise, it is not.
@item idle_task_stack_size
is the size of the RTEMS idle task stack in bytes.
If this number is less than MINIMUM_STACK_SIZE, then the
idle task's stack will be MINIMUM_STACK_SIZE in byte.
@item interrupt_stack_size
is the size of the RTEMS
allocated interrupt stack in bytes. This value must be at least
as large as MINIMUM_STACK_SIZE.
@item extra_mpci_receive_server_stack
is the extra stack space allocated for the RTEMS MPCI receive server task
in bytes. The MPCI receive server may invoke nearly all directives and
may require extra stack space on some targets.
@item stack_allocate_hook
is the address of the optional user provided routine which allocates
memory for task stacks. If this hook is not NULL, then a stack_free_hook
must be provided as well.
@item stack_free_hook
is the address of the optional user provided routine which frees
memory for task stacks. If this hook is not NULL, then a stack_allocate_hook
must be provided as well.
@item interrupt_segment
is the value of the selector which should be placed in a segment
register to access the Interrupt Descriptor Table.
@item interrupt_vector_table
is the base address of the Interrupt Descriptor Table relative to the
interrupt_segment.
@end table
The contents of the i386 Interrupt Descriptor Table
are discussed in Intel's i386 User's Manual. Structure
definitions for the i386 IDT is provided by including the file
rtems.h.

773
doc/cpu_supplement/m68k.t Normal file
View File

@@ -0,0 +1,773 @@
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@ifinfo
@end ifinfo
@chapter Motorola M68xxx and Coldfire Specific Information
The Real Time Executive for Multiprocessor Systems (RTEMS)
is designed to be portable across multiple processor
architectures. However, the nature of real-time systems makes
it essential that the application designer understand certain
processor dependent implementation details. These processor
dependencies include calling convention, board support package
issues, interrupt processing, exact RTEMS memory requirements,
performance data, header files, and the assembly language
interface to the executive.
This document discusses the Motorola MC68xxx
architecture dependencies in this port of RTEMS. The MC68xxx
family has a wide variety of CPU models within it. 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.
It is highly recommended that the Motorola MC68xxx
RTEMS application developer obtain and become familiar with the
documentation for the processor being used as well as the
documentation for the family as a whole.
@subheading Architecture Documents
For information on the Motorola MC68xxx architecture,
refer to the following documents available from Motorola
(@file{http//www.moto.com/}):
@itemize @bullet
@item @cite{M68000 Family Reference, Motorola, FR68K/D}.
@end itemize
@subheading MODEL SPECIFIC DOCUMENTS
For information on specific processor models and
their associated coprocessors, refer to the following documents:
@itemize @bullet
@item @cite{MC68020 User's Manual, Motorola, MC68020UM/AD}.
@item @cite{MC68881/MC68882 Floating-Point Coprocessor User's
Manual, Motorola, MC68881UM/AD}.
@end itemize
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section CPU Model Dependent Features
Microprocessors are generally classified into
families with a variety of CPU models or implementations within
that family. Within a processor family, there is a high level
of binary compatibility. This family may be based on either an
architectural specification or on maintaining compatibility with
a popular processor. Recent microprocessor families such as the
SPARC or PowerPC are based on an architectural specification
which is independent or any particular CPU model or
implementation. Older families such as the M68xxx and the iX86
evolved as the manufacturer strived to produce higher
performance processor models which maintained binary
compatibility with older models.
RTEMS takes advantage of the similarity of the
various models within a CPU family. Although the models do vary
in significant ways, the high level of compatibility makes it
possible to share the bulk of the CPU dependent executive code
across the entire family. Each processor family supported by
RTEMS has a list of features which vary between CPU models
within a family. For example, the most common model dependent
feature regardless of CPU family is the presence or absence of a
floating point unit or coprocessor. When defining the list of
features present on a particular CPU model, one simply notes
that floating point hardware is or is not present and defines a
single constant appropriately. Conditional compilation is
utilized to include the appropriate source code for this CPU
model's feature set. It is important to note that this means
that RTEMS is thus compiled using the appropriate feature set
and compilation flags optimal for this CPU model used. The
alternative would be to generate a binary which would execute on
all family members using only the features which were always
present.
This chapter presents the set of features which vary
across SPARC implementations and 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 defined on the compilation command line.
@subsection CPU Model Name
The macro CPU_MODEL_NAME is a string which designates
the name of this CPU model. For example, for the MC68020
processor, this macro is set to the string "mc68020".
@subsection Floating Point Unit
The macro M68K_HAS_FPU is set to 1 to indicate that
this CPU model has a hardware floating point unit and 0
otherwise. It does not matter whether the hardware floating
point support is incorporated on-chip or is an external
coprocessor.
@subsection BFFFO Instruction
The macro M68K_HAS_BFFFO is set to 1 to indicate that
this CPU model has the bfffo instruction.
@subsection Vector Base Register
The macro M68K_HAS_VBR is set to 1 to indicate that
this CPU model has a vector base register (vbr).
@subsection 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.
@subsection 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.
@subsection 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.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Calling Conventions
Each high-level language compiler generates
subroutine entry and exit code based upon a set of rules known
as the compiler's calling convention. These rules address the
following issues:
@itemize @bullet
@item register preservation and usage
@item parameter passing
@item call and return mechanism
@end itemize
A compiler's calling convention is of importance when
interfacing to subroutines written in another language either
assembly or high-level. Even when the high-level language and
target processor are the same, different compilers may use
different calling conventions. As a result, calling conventions
are both processor and compiler dependent.
@subsection Processor Background
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.
@subsection Calling Mechanism
All RTEMS directives are invoked using either a bsr
or jsr instruction and return to the user application via the
rts instruction.
@subsection 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.
@subsection 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:
@example
@group
push third argument
push second argument
push first argument
invoke directive
remove arguments from the stack
@end group
@end example
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.
@subsection User-Provided Routines
All user-provided routines invoked by RTEMS, such as
user extensions, device drivers, and MPCI routines, must also
adhere to these calling conventions.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Memory Model
A processor may support any combination of memory
models ranging from pure physical addressing to complex demand
paged virtual memory systems. RTEMS supports a flat memory
model which ranges contiguously over the processor's allowable
address space. RTEMS does not support segmentation or virtual
memory of any kind. The appropriate memory model for RTEMS
provided by the targeted processor and related characteristics
of that model are described in this chapter.
@subsection Flat 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.
@c
@c Interrupt Stack Frame Picture
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Interrupt Processing
Different types of processors respond to the
occurrence of an interrupt in its own unique fashion. In
addition, each processor type provides a control mechanism to
allow for the proper handling of an interrupt. The processor
dependent response to the interrupt modifies the current
execution state and results in a change in the execution stream.
Most processors require that an interrupt handler utilize some
special control mechanisms to return to the normal processing
stream. Although RTEMS hides many of the processor dependent
details of interrupt processing, it is important to understand
how the RTEMS interrupt manager is mapped onto the processor's
unique architecture. Discussed in this chapter are the MC68xxx's
interrupt response and control mechanisms as they pertain to
RTEMS.
@subsection 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.
@subsubsection Models Without Separate Interrupt Stacks
Upon receipt of an interrupt the MC68xxx family
members without separate interrupt stacks automatically perform
the following actions:
@itemize @bullet
@item To Be Written
@end itemize
@subsubsection Models With Separate Interrupt Stacks
Upon receipt of an interrupt the MC68xxx family
members with separate interrupt stacks automatically perform the
following actions:
@itemize @bullet
@item saves the current status register (SR),
@item clears the master/interrupt (M) bit of the SR to
indicate the switch from master state to interrupt state,
@item sets the privilege mode to supervisor,
@item suppresses tracing,
@item sets the interrupt mask level equal to the level of the
interrupt being serviced,
@item 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,
@item 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.
@end itemize
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 following shows the Interrupt Stack Frame for
MC68xxx CPU models with separate interrupt stacks:
@ifset use-ascii
@example
@group
+----------------------+
| Status Register | 0x0
+----------------------+
| Program Counter High | 0x2
+----------------------+
| Program Counter Low | 0x4
+----------------------+
| Format/Vector Offset | 0x6
+----------------------+
@end group
@end example
@end ifset
@ifset use-tex
@sp 1
@tex
\centerline{\vbox{\offinterlineskip\halign{
\strut\vrule#&
\hbox to 2.00in{\enskip\hfil#\hfil}&
\vrule#&
\hbox to 0.50in{\enskip\hfil#\hfil}
\cr
\multispan{3}\hrulefill\cr
& Status Register && 0x0\cr
\multispan{3}\hrulefill\cr
& Program Counter High && 0x2\cr
\multispan{3}\hrulefill\cr
& Program Counter Low && 0x4\cr
\multispan{3}\hrulefill\cr
& Format/Vector Offset && 0x6\cr
\multispan{3}\hrulefill\cr
}}\hfil}
@end tex
@end ifset
@ifset use-html
@html
<CENTER>
<TABLE COLS=2 WIDTH="40%" BORDER=2>
<TR><TD ALIGN=center><STRONG>Status Register</STRONG></TD>
<TD ALIGN=center>0x0</TD></TR>
<TR><TD ALIGN=center><STRONG>Program Counter High</STRONG></TD>
<TD ALIGN=center>0x2</TD></TR>
<TR><TD ALIGN=center><STRONG>Program Counter Low</STRONG></TD>
<TD ALIGN=center>0x4</TD></TR>
<TR><TD ALIGN=center><STRONG>Format/Vector Offset</STRONG></TD>
<TD ALIGN=center>0x6</TD></TR>
</TABLE>
</CENTER>
@end html
@end ifset
@subsection 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:
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:
@example
//
// Real vector table at 0
//
.long initial_sp
.long initial_pc
.long myhandler+0x02000000
.long myhandler+0x03000000
.long myhandler+0x04000000
...
.long myhandler+0xff000000
//
// This handler will jump to the interrupt routine of which
// the address is stored at VBR[ vector_no ]
// The registers and stackframe will be intact, the interrupt
// 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;
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
// restore the stack
(1) If 'myhandler' is guaranteed to be in the first 64K, e.g. just
after the vector table then that insn is not needed.
@end example
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 :-)
@subsection 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.
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.
@subsection Disabling of Interrupts by RTEMS
During the execution of directive calls, critical
sections of code may be executed. When these sections are
encountered, RTEMS disables interrupts to level seven (7) before
the execution of this section and restores them to the previous
level upon completion of the section. RTEMS has been optimized
to insure that interrupts are disabled for less than
RTEMS_MAXIMUM_DISABLE_PERIOD microseconds on a
RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ Mhz MC68020 with
zero wait states. These numbers will vary based the
number of wait states and processor speed present on the target board.
[NOTE: The maximum period with interrupts disabled is hand calculated. This
calculation was last performed for Release
RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.]
Non-maskable interrupts (NMI) cannot be disabled, and
ISRs which execute at this level MUST NEVER issue RTEMS system
calls. If a directive is invoked, unpredictable results may
occur due to the inability of RTEMS to protect its critical
sections. However, ISRs that make no system calls may safely
execute as non-maskable interrupts.
@subsection Interrupt Stack
RTEMS allocates the interrupt stack from the
Workspace Area. The amount of memory allocated for the
interrupt stack is determined by the interrupt_stack_size field
in the CPU Configuration Table. During the initialization
process, RTEMS will install its interrupt stack.
The MC68xxx port of RTEMS supports a software managed
dedicated interrupt stack on those CPU models which do not
support a separate interrupt stack in hardware.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Default Fatal Error Processing
Upon detection of a fatal error by either the
application or RTEMS the fatal error manager is invoked. The
fatal error manager will invoke the user-supplied fatal error
handlers. If no user-supplied handlers are configured, the
RTEMS provided default fatal error handler is invoked. If the
user-supplied fatal error handlers return to the executive the
default fatal error handler is then invoked. This chapter
describes the precise operations of the default fatal error
handler.
@subsection Default Fatal Error Handler Operations
The default fatal error handler which is invoked by
the fatal_error_occurred directive when there is no user handler
configured or the user handler returns control to RTEMS. The
default fatal error handler disables processor interrupts to
level 7, places the error code in D0, and executes a stop
instruction to simulate a halt processor instruction.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Board Support Packages
An RTEMS Board Support Package (BSP) must be designed
to support a particular processor and target board combination.
This chapter presents a discussion of MC68020 specific BSP
issues. For more information on developing a BSP, refer to the
chapter titled Board Support Packages in the RTEMS
Applications User's Guide.
@subsection 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:
@itemize @bullet
@item The tracing bits of the status register are cleared to
disable tracing.
@item The supervisor interrupt state is entered by setting the
supervisor (S) bit and clearing the master/interrupt (M) bit of
the status register.
@item The interrupt mask of the status register is set to
level 7 to effectively disable all maskable interrupts.
@item The vector base register (VBR) is set to zero.
@item The cache control register (CACR) is set to zero to
disable and freeze the processor cache.
@item The interrupt stack pointer (ISP) is set to the value
stored at vector 0 (bytes 0-3) of the exception vector table
(EVT).
@item The program counter (PC) is set to the value stored at
vector 1 (bytes 4-7) of the EVT.
@item The processor begins execution at the address stored in
the PC.
@end itemize
@subsection 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 initialize
executive directive, the VBR MUST be set before this directive
is invoked to insure 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:
@itemize @bullet
@item Must leave the S bit of the status register set so that
the MC68020 remains in the supervisor state.
@item Must set the M bit of the status register to remove the
MC68020 from the interrupt state.
@item 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.
@item Must initialize the MC68020's vector table.
@end itemize
Note that the BSP is not responsible for allocating
or installing the interrupt stack. RTEMS does this
automatically as part of initialization. If the BSP does not
install an interrupt stack and -- for whatever reason -- an
interrupt occurs before initialize_executive is invoked, then
the results are unpredictable.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Processor Dependent Information Table
Any highly processor dependent information required
to describe a processor to RTEMS is provided in the CPU
Dependent Information Table. This table is not required for all
processors supported by RTEMS. This chapter describes the
contents, if any, for a particular processor type.
@subsection CPU Dependent Information Table
The MC68xxx version of the RTEMS CPU Dependent
Information Table contains the information required to interface
a Board Support Package and RTEMS on the MC68xxx. This
information is provided to allow RTEMS to interoperate
effectively with the BSP. The C structure definition is given
here:
@example
@group
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 */
m68k_isr *interrupt_vector_table;
@} rtems_cpu_table;
@end group
@end example
@table @code
@item pretasking_hook
is the address of the user provided routine which is invoked
once RTEMS APIs are initialized. This routine will be invoked
before any system tasks are created. Interrupts are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item predriver_hook
is the address of the user provided
routine that is invoked immediately before the
the device drivers and MPCI are initialized. RTEMS
initialization is complete but interrupts and tasking are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item postdriver_hook
is the address of the user provided
routine that is invoked immediately after the
the device drivers and MPCI are initialized. RTEMS
initialization is complete but interrupts and tasking are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item idle_task
is the address of the optional user
provided routine which is used as the system's IDLE task. If
this field is not NULL, then the RTEMS default IDLE task is not
used. This field may be NULL to indicate that the default IDLE
is to be used.
@item do_zero_of_workspace
indicates whether RTEMS should
zero the Workspace as part of its initialization. If set to
TRUE, the Workspace is zeroed. Otherwise, it is not.
@item idle_task_stack_size
is the size of the RTEMS idle task stack in bytes.
If this number is less than MINIMUM_STACK_SIZE, then the
idle task's stack will be MINIMUM_STACK_SIZE in byte.
@item interrupt_stack_size
is the size of the RTEMS
allocated interrupt stack in bytes. This value must be at least
as large as MINIMUM_STACK_SIZE.
@item extra_mpci_receive_server_stack
is the extra stack space allocated for the RTEMS MPCI receive server task
in bytes. The MPCI receive server may invoke nearly all directives and
may require extra stack space on some targets.
@item stack_allocate_hook
is the address of the optional user provided routine which allocates
memory for task stacks. If this hook is not NULL, then a stack_free_hook
must be provided as well.
@item stack_free_hook
is the address of the optional user provided routine which frees
memory for task stacks. If this hook is not NULL, then a stack_allocate_hook
must be provided as well.
@item interrupt_vector_table
is the base address of the CPU's Exception Vector Table.
@end table

677
doc/cpu_supplement/mips.t Normal file
View File

@@ -0,0 +1,677 @@
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@ifinfo
@end ifinfo
@chapter MIPS Specific Information
The Real Time Executive for Multiprocessor Systems (RTEMS)
is designed to be portable across multiple processor
architectures. However, the nature of real-time systems makes
it essential that the application designer understand certain
processor dependent implementation details. These processor
dependencies include calling convention, board support package
issues, interrupt processing, exact RTEMS memory requirements,
performance data, header files, and the assembly language
interface to the executive.
This document discusses the VENDOR XXX
architecture dependencies in this port of RTEMS. The XXX
family has a wide variety of CPU models within it. The part
numbers ...
XXX fill in some things here
It is highly recommended that the XXX
RTEMS application developer obtain and become familiar with the
documentation for the processor being used as well as the
documentation for the family as a whole.
@subheading Architecture Documents
IDT docs are online at http://www.idt.com/products/risc/Welcome.html
For information on the XXX architecture,
refer to the following documents available from VENDOR
(@file{http//www.XXX.com/}):
@itemize @bullet
@item @cite{XXX Family Reference, VENDOR, PART NUMBER}.
@end itemize
@subheading MODEL SPECIFIC DOCUMENTS
For information on specific processor models and
their associated coprocessors, refer to the following documents:
@itemize @bullet
@item @cite{XXX MODEL Manual, VENDOR, PART NUMBER}.
@item @cite{XXX MODEL Manual, VENDOR, PART NUMBER}.
@end itemize
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section CPU Model Dependent Features
Microprocessors are generally classified into
families with a variety of CPU models or implementations within
that family. Within a processor family, there is a high level
of binary compatibility. This family may be based on either an
architectural specification or on maintaining compatibility with
a popular processor. Recent microprocessor families such as the
SPARC or PowerPC are based on an architectural specification
which is independent or any particular CPU model or
implementation. Older families such as the M68xxx and the iX86
evolved as the manufacturer strived to produce higher
performance processor models which maintained binary
compatibility with older models.
RTEMS takes advantage of the similarity of the
various models within a CPU family. Although the models do vary
in significant ways, the high level of compatibility makes it
possible to share the bulk of the CPU dependent executive code
across the entire family. Each processor family supported by
RTEMS has a list of features which vary between CPU models
within a family. For example, the most common model dependent
feature regardless of CPU family is the presence or absence of a
floating point unit or coprocessor. When defining the list of
features present on a particular CPU model, one simply notes
that floating point hardware is or is not present and defines a
single constant appropriately. Conditional compilation is
utilized to include the appropriate source code for this CPU
model's feature set. It is important to note that this means
that RTEMS is thus compiled using the appropriate feature set
and compilation flags optimal for this CPU model used. The
alternative would be to generate a binary which would execute on
all family members using only the features which were always
present.
This chapter presents the set of features which vary
across SPARC implementations and are of importance to RTEMS.
The set of CPU model feature macros are defined in the file
cpukit/score/cpu/XXX/XXX.h based upon the particular CPU
model defined on the compilation command line.
@subsection CPU Model Name
The macro CPU_MODEL_NAME is a string which designates
the name of this CPU model. For example, for the MODEL
processor, this macro is set to the string "XXX".
@subsection Floating Point Unit
The macro XXX_HAS_FPU is set to 1 to indicate that
this CPU model has a hardware floating point unit and 0
otherwise. It does not matter whether the hardware floating
point support is incorporated on-chip or is an external
coprocessor.
@subsection Another Optional Feature
The macro XXX
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Calling Conventions
Each high-level language compiler generates
subroutine entry and exit code based upon a set of rules known
as the compiler's calling convention. These rules address the
following issues:
@itemize @bullet
@item register preservation and usage
@item parameter passing
@item call and return mechanism
@end itemize
A compiler's calling convention is of importance when
interfacing to subroutines written in another language either
assembly or high-level. Even when the high-level language and
target processor are the same, different compilers may use
different calling conventions. As a result, calling conventions
are both processor and compiler dependent.
@subsection Processor Background
The MC68xxx architecture supports a simple yet
effective call and return mechanism. A subroutine is invoked
via the branch to subroutine (@code{XXX}) or the jump to subroutine
(@code{XXX}) instructions. These instructions push the return address
on the current stack. The return from subroutine (@code{XXX})
instruction pops the return address off the current stack and
transfers control to that instruction. It is is important to
note that the XXX 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.
@subsection Calling Mechanism
All RTEMS directives are invoked using either a @code{XXX}
or @code{XXX} instruction and return to the user application via the
@code{XXX} instruction.
@subsection Register Usage
As discussed above, the @code{XXX} and @code{XXX} instructions do
not automatically save any registers. RTEMS uses the registers
@b{D0}, @b{D1}, @b{A0}, and @b{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.
@subsection Parameter Passing
RTEMS assumes that arguments are placed on the
current stack before the directive is invoked via the @code{XXX} or @code{XXX}
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:
@example
@group
push third argument
push second argument
push first argument
invoke directive
remove arguments from the stack
@end group
@end example
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.
@subsection User-Provided Routines
All user-provided routines invoked by RTEMS, such as
user extensions, device drivers, and MPCI routines, must also
adhere to these calling conventions.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Memory Model
A processor may support any combination of memory
models ranging from pure physical addressing to complex demand
paged virtual memory systems. RTEMS supports a flat memory
model which ranges contiguously over the processor's allowable
address space. RTEMS does not support segmentation or virtual
memory of any kind. The appropriate memory model for RTEMS
provided by the targeted processor and related characteristics
of that model are described in this chapter.
@subsection Flat Memory Model
The XXX 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 XXX family members such as the
XXX, XXX, and XXX support virtual memory and
segmentation. The XXX requires external hardware support
such as the XXX 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 XXX family members.
@c
@c Interrupt Stack Frame Picture
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Interrupt Processing
Different types of processors respond to the
occurrence of an interrupt in its own unique fashion. In
addition, each processor type provides a control mechanism to
allow for the proper handling of an interrupt. The processor
dependent response to the interrupt modifies the current
execution state and results in a change in the execution stream.
Most processors require that an interrupt handler utilize some
special control mechanisms to return to the normal processing
stream. Although RTEMS hides many of the processor dependent
details of interrupt processing, it is important to understand
how the RTEMS interrupt manager is mapped onto the processor's
unique architecture. Discussed in this chapter are the XXX's
interrupt response and control mechanisms as they pertain to
RTEMS.
@subsection Vectoring of an Interrupt Handler
Depending on whether or not the particular CPU
supports a separate interrupt stack, the XXX family has two
different interrupt handling models.
@subsubsection Models Without Separate Interrupt Stacks
Upon receipt of an interrupt the XXX family
members without separate interrupt stacks automatically perform
the following actions:
@itemize @bullet
@item To Be Written
@end itemize
@subsubsection Models With Separate Interrupt Stacks
Upon receipt of an interrupt the XXX family
members with separate interrupt stacks automatically perform the
following actions:
@itemize @bullet
@item saves the current status register (SR),
@item clears the master/interrupt (M) bit of the SR to
indicate the switch from master state to interrupt state,
@item sets the privilege mode to supervisor,
@item suppresses tracing,
@item sets the interrupt mask level equal to the level of the
interrupt being serviced,
@item 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,
@item 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.
@end itemize
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 following shows the Interrupt Stack Frame for
XXX CPU models with separate interrupt stacks:
@ifset use-ascii
@example
@group
+----------------------+
| Status Register | 0x0
+----------------------+
| Program Counter High | 0x2
+----------------------+
| Program Counter Low | 0x4
+----------------------+
| Format/Vector Offset | 0x6
+----------------------+
@end group
@end example
@end ifset
@ifset use-tex
@sp 1
@tex
\centerline{\vbox{\offinterlineskip\halign{
\strut\vrule#&
\hbox to 2.00in{\enskip\hfil#\hfil}&
\vrule#&
\hbox to 0.50in{\enskip\hfil#\hfil}
\cr
\multispan{3}\hrulefill\cr
& Status Register && 0x0\cr
\multispan{3}\hrulefill\cr
& Program Counter High && 0x2\cr
\multispan{3}\hrulefill\cr
& Program Counter Low && 0x4\cr
\multispan{3}\hrulefill\cr
& Format/Vector Offset && 0x6\cr
\multispan{3}\hrulefill\cr
}}\hfil}
@end tex
@end ifset
@ifset use-html
@html
<CENTER>
<TABLE COLS=2 WIDTH="40%" BORDER=2>
<TR><TD ALIGN=center><STRONG>Status Register</STRONG></TD>
<TD ALIGN=center>0x0</TD></TR>
<TR><TD ALIGN=center><STRONG>Program Counter High</STRONG></TD>
<TD ALIGN=center>0x2</TD></TR>
<TR><TD ALIGN=center><STRONG>Program Counter Low</STRONG></TD>
<TD ALIGN=center>0x4</TD></TR>
<TR><TD ALIGN=center><STRONG>Format/Vector Offset</STRONG></TD>
<TD ALIGN=center>0x6</TD></TR>
</TABLE>
</CENTER>
@end html
@end ifset
@subsection Interrupt Levels
Eight levels (0-7) of interrupt priorities are
supported by XXX 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
XXX family only supports eight. RTEMS interrupt levels 0
through 7 directly correspond to XXX interrupt levels. All
other RTEMS interrupt levels are undefined and their behavior is
unpredictable.
@subsection Disabling of Interrupts by RTEMS
During the execution of directive calls, critical
sections of code may be executed. When these sections are
encountered, RTEMS disables interrupts to level seven (7) before
the execution of this section and restores them to the previous
level upon completion of the section. RTEMS has been optimized
to insure that interrupts are disabled for less than
RTEMS_MAXIMUM_DISABLE_PERIOD microseconds on a
RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ Mhz processor with
zero wait states. These numbers will vary based the
number of wait states and processor speed present on the target board.
[NOTE: The maximum period with interrupts disabled is hand calculated. This
calculation was last performed for Release
RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.]
Non-maskable interrupts (NMI) cannot be disabled, and
ISRs which execute at this level MUST NEVER issue RTEMS system
calls. If a directive is invoked, unpredictable results may
occur due to the inability of RTEMS to protect its critical
sections. However, ISRs that make no system calls may safely
execute as non-maskable interrupts.
@subsection Interrupt Stack
RTEMS allocates the interrupt stack from the
Workspace Area. The amount of memory allocated for the
interrupt stack is determined by the interrupt_stack_size field
in the CPU Configuration Table. During the initialization
process, RTEMS will install its interrupt stack.
The mips port of RTEMS supports a software managed
dedicated interrupt stack on those CPU models which do not
support a separate interrupt stack in hardware.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Default Fatal Error Processing
Upon detection of a fatal error by either the
application or RTEMS the fatal error manager is invoked. The
fatal error manager will invoke the user-supplied fatal error
handlers. If no user-supplied handlers are configured, the
RTEMS provided default fatal error handler is invoked. If the
user-supplied fatal error handlers return to the executive the
default fatal error handler is then invoked. This chapter
describes the precise operations of the default fatal error
handler.
@subsection Default Fatal Error Handler Operations
The default fatal error handler which is invoked by
the @code{rtems_fatal_error_occurred} directive when there is
no user handler configured or the user handler returns control to
RTEMS. The default fatal error handler disables processor interrupts,
places the error code in @b{XXX}, and executes a @code{XXX}
instruction to simulate a halt processor instruction.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Board Support Packages
An RTEMS Board Support Package (BSP) must be designed
to support a particular processor and target board combination.
This chapter presents a discussion of XXX specific BSP
issues. For more information on developing a BSP, refer to the
chapter titled Board Support Packages in the RTEMS
Applications User's Guide.
@subsection System Reset
An RTEMS based application is initiated or
re-initiated when the XXX processor is reset. When the
XXX is reset, the processor performs the following actions:
@itemize @bullet
@item The tracing bits of the status register are cleared to
disable tracing.
@item The supervisor interrupt state is entered by setting the
supervisor (S) bit and clearing the master/interrupt (M) bit of
the status register.
@item The interrupt mask of the status register is set to
level 7 to effectively disable all maskable interrupts.
@item The vector base register (VBR) is set to zero.
@item The cache control register (CACR) is set to zero to
disable and freeze the processor cache.
@item The interrupt stack pointer (ISP) is set to the value
stored at vector 0 (bytes 0-3) of the exception vector table
(EVT).
@item The program counter (PC) is set to the value stored at
vector 1 (bytes 4-7) of the EVT.
@item The processor begins execution at the address stored in
the PC.
@end itemize
@subsection 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 XXX's VBR value. Because interrupts
are enabled automatically by RTEMS as part of the initialize
executive directive, the VBR MUST be set before this directive
is invoked to insure 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 XXX version has the following
specific requirements:
@itemize @bullet
@item Must leave the S bit of the status register set so that
the XXX remains in the supervisor state.
@item Must set the M bit of the status register to remove the
XXX from the interrupt state.
@item 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.
@item Must initialize the XXX's vector table.
@end itemize
Note that the BSP is not responsible for allocating
or installing the interrupt stack. RTEMS does this
automatically as part of initialization. If the BSP does not
install an interrupt stack and -- for whatever reason -- an
interrupt occurs before initialize_executive is invoked, then
the results are unpredictable.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Processor Dependent Information Table
Any highly processor dependent information required
to describe a processor to RTEMS is provided in the CPU
Dependent Information Table. This table is not required for all
processors supported by RTEMS. This chapter describes the
contents, if any, for a particular processor type.
@subsection CPU Dependent Information Table
The XXX version of the RTEMS CPU Dependent
Information Table contains the information required to interface
a Board Support Package and RTEMS on the XXX. This
information is provided to allow RTEMS to interoperate
effectively with the BSP. The C structure definition is given
here:
@example
@group
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 */
/* XXX CPU family dependent stuff */
@} rtems_cpu_table;
@end group
@end example
@table @code
@item pretasking_hook
is the address of the user provided routine which is invoked
once RTEMS APIs are initialized. This routine will be invoked
before any system tasks are created. Interrupts are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item predriver_hook
is the address of the user provided
routine that is invoked immediately before the
the device drivers and MPCI are initialized. RTEMS
initialization is complete but interrupts and tasking are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item postdriver_hook
is the address of the user provided
routine that is invoked immediately after the
the device drivers and MPCI are initialized. RTEMS
initialization is complete but interrupts and tasking are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item idle_task
is the address of the optional user
provided routine which is used as the system's IDLE task. If
this field is not NULL, then the RTEMS default IDLE task is not
used. This field may be NULL to indicate that the default IDLE
is to be used.
@item do_zero_of_workspace
indicates whether RTEMS should
zero the Workspace as part of its initialization. If set to
TRUE, the Workspace is zeroed. Otherwise, it is not.
@item idle_task_stack_size
is the size of the RTEMS idle task stack in bytes.
If this number is less than MINIMUM_STACK_SIZE, then the
idle task's stack will be MINIMUM_STACK_SIZE in byte.
@item interrupt_stack_size
is the size of the RTEMS
allocated interrupt stack in bytes. This value must be at least
as large as MINIMUM_STACK_SIZE.
@item extra_mpci_receive_server_stack
is the extra stack space allocated for the RTEMS MPCI receive server task
in bytes. The MPCI receive server may invoke nearly all directives and
may require extra stack space on some targets.
@item stack_allocate_hook
is the address of the optional user provided routine which allocates
memory for task stacks. If this hook is not NULL, then a stack_free_hook
must be provided as well.
@item stack_free_hook
is the address of the optional user provided routine which frees
memory for task stacks. If this hook is not NULL, then a stack_allocate_hook
must be provided as well.
@item XXX
is where the CPU family dependent stuff goes.
@end table

1043
doc/cpu_supplement/powerpc.t Normal file
View File

File diff suppressed because it is too large Load Diff

25
doc/cpu_supplement/preface.texi Normal file
View File

@@ -0,0 +1,25 @@
@c
@c COPYRIGHT (c) 1988-2006.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@ifinfo
@node Preface, ARM Specific Information, Top, Top
@end ifinfo
@unnumbered Preface
The Real Time Executive for Multiprocessor Systems
(RTEMS) is designed to be portable across multiple processor
architectures. However, the nature of real-time systems makes
it essential that the application designer understand certain
processor dependent implementation details. These processor
dependencies include calling convention, board support package
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.

685
doc/cpu_supplement/sh.t Normal file
View File

@@ -0,0 +1,685 @@
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@ifinfo
@end ifinfo
@chapter SuperH Specific Information
The Real Time Executive for Multiprocessor Systems (RTEMS)
is designed to be portable across multiple processor
architectures. However, the nature of real-time systems makes
it essential that the application designer understand certain
processor dependent implementation details. These processor
dependencies include calling convention, board support package
issues, interrupt processing, exact RTEMS memory requirements,
performance data, header files, and the assembly language
interface to the executive.
This document discusses the VENDOR XXX
architecture dependencies in this port of RTEMS. The XXX
family has a wide variety of CPU models within it. The part
numbers ...
XXX fill in some things here
It is highly recommended that the XXX
RTEMS application developer obtain and become familiar with the
documentation for the processor being used as well as the
documentation for the family as a whole.
@subheading Architecture Documents
For information on the XXX architecture,
refer to the following documents available from VENDOR
(@file{http//www.XXX.com/}):
@itemize @bullet
@item @cite{XXX Family Reference, VENDOR, PART NUMBER}.
@end itemize
@subheading MODEL SPECIFIC DOCUMENTS
For information on specific processor models and
their associated coprocessors, refer to the following documents:
@itemize @bullet
@item @cite{XXX MODEL Manual, VENDOR, PART NUMBER}.
@item @cite{XXX MODEL Manual, VENDOR, PART NUMBER}.
@end itemize
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section CPU Model Dependent Features
Microprocessors are generally classified into
families with a variety of CPU models or implementations within
that family. Within a processor family, there is a high level
of binary compatibility. This family may be based on either an
architectural specification or on maintaining compatibility with
a popular processor. Recent microprocessor families such as the
SPARC or PowerPC are based on an architectural specification
which is independent or any particular CPU model or
implementation. Older families such as the M68xxx and the iX86
evolved as the manufacturer strived to produce higher
performance processor models which maintained binary
compatibility with older models.
RTEMS takes advantage of the similarity of the
various models within a CPU family. Although the models do vary
in significant ways, the high level of compatibility makes it
possible to share the bulk of the CPU dependent executive code
across the entire family. Each processor family supported by
RTEMS has a list of features which vary between CPU models
within a family. For example, the most common model dependent
feature regardless of CPU family is the presence or absence of a
floating point unit or coprocessor. When defining the list of
features present on a particular CPU model, one simply notes
that floating point hardware is or is not present and defines a
single constant appropriately. Conditional compilation is
utilized to include the appropriate source code for this CPU
model's feature set. It is important to note that this means
that RTEMS is thus compiled using the appropriate feature set
and compilation flags optimal for this CPU model used. The
alternative would be to generate a binary which would execute on
all family members using only the features which were always
present.
This chapter presents the set of features which vary
across SPARC implementations and are of importance to RTEMS.
The set of CPU model feature macros are defined in the file
cpukit/score/cpu/XXX/XXX.h based upon the particular CPU
model defined on the compilation command line.
@subsection CPU Model Name
The macro CPU_MODEL_NAME is a string which designates
the name of this CPU model. For example, for the MODEL
processor, this macro is set to the string "XXX".
@subsection Floating Point Unit
The macro XXX_HAS_FPU is set to 1 to indicate that
this CPU model has a hardware floating point unit and 0
otherwise. It does not matter whether the hardware floating
point support is incorporated on-chip or is an external
coprocessor.
@subsection Another Optional Feature
The macro XXX
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Calling Conventions
Each high-level language compiler generates
subroutine entry and exit code based upon a set of rules known
as the compiler's calling convention. These rules address the
following issues:
@itemize @bullet
@item register preservation and usage
@item parameter passing
@item call and return mechanism
@end itemize
A compiler's calling convention is of importance when
interfacing to subroutines written in another language either
assembly or high-level. Even when the high-level language and
target processor are the same, different compilers may use
different calling conventions. As a result, calling conventions
are both processor and compiler dependent.
The Hitachi SH architecture supports a simple yet
effective call and return mechanism. A subroutine is invoked
via the branch to subroutine (XXX) or the jump to subroutine
(XXX) 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.
@subsection Calling Mechanism
All RTEMS directives are invoked using either a bsr
or jsr instruction and return to the user application via the
rts instruction.
@subsection 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.
> > The SH1 has 16 general registers (r0..r15)
> > r0..r3 used as general volatile registers
> > r4..r7 used to pass up to 4 arguments to functions, arguments above 4 are
> > passed via the stack)
> > r8..13 caller saved registers (i.e. push them to the stack if you need them
> > inside of a function)
> > r14 frame pointer
> > r15 stack pointer
>
@subsection 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:
@example
@group
push third argument
push second argument
push first argument
invoke directive
remove arguments from the stack
@end group
@end example
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.
@subsection User-Provided Routines
All user-provided routines invoked by RTEMS, such as
user extensions, device drivers, and MPCI routines, must also
adhere to these calling conventions.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Memory Model
A processor may support any combination of memory
models ranging from pure physical addressing to complex demand
paged virtual memory systems. RTEMS supports a flat memory
model which ranges contiguously over the processor's allowable
address space. RTEMS does not support segmentation or virtual
memory of any kind. The appropriate memory model for RTEMS
provided by the targeted processor and related characteristics
of that model are described in this chapter.
@subsection Flat Memory Model
The XXX 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 XXX family members such as the
XXX, XXX, and XXX support virtual memory and
segmentation. The XXX requires external hardware support
such as the XXX 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 XXX family members.
@c
@c Interrupt Stack Frame Picture
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Interrupt Processing
Different types of processors respond to the
occurrence of an interrupt in its own unique fashion. In
addition, each processor type provides a control mechanism to
allow for the proper handling of an interrupt. The processor
dependent response to the interrupt modifies the current
execution state and results in a change in the execution stream.
Most processors require that an interrupt handler utilize some
special control mechanisms to return to the normal processing
stream. Although RTEMS hides many of the processor dependent
details of interrupt processing, it is important to understand
how the RTEMS interrupt manager is mapped onto the processor's
unique architecture. Discussed in this chapter are the SH's
interrupt response and control mechanisms as they pertain to
RTEMS.
@subsection Vectoring of an Interrupt Handler
Depending on whether or not the particular CPU
supports a separate interrupt stack, the SH family has two
different interrupt handling models.
@subsubsection Models Without Separate Interrupt Stacks
Upon receipt of an interrupt the SH family
members without separate interrupt stacks automatically perform
the following actions:
@itemize @bullet
@item To Be Written
@end itemize
@subsubsection Models With Separate Interrupt Stacks
Upon receipt of an interrupt the SH family
members with separate interrupt stacks automatically perform the
following actions:
@itemize @bullet
@item saves the current status register (SR),
@item clears the master/interrupt (M) bit of the SR to
indicate the switch from master state to interrupt state,
@item sets the privilege mode to supervisor,
@item suppresses tracing,
@item sets the interrupt mask level equal to the level of the
interrupt being serviced,
@item 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,
@item 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.
@end itemize
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 following shows the Interrupt Stack Frame for
XXX CPU models with separate interrupt stacks:
@ifset use-ascii
@example
@group
+----------------------+
| Status Register | 0x0
+----------------------+
| Program Counter High | 0x2
+----------------------+
| Program Counter Low | 0x4
+----------------------+
| Format/Vector Offset | 0x6
+----------------------+
@end group
@end example
@end ifset
@ifset use-tex
@sp 1
@tex
\centerline{\vbox{\offinterlineskip\halign{
\strut\vrule#&
\hbox to 2.00in{\enskip\hfil#\hfil}&
\vrule#&
\hbox to 0.50in{\enskip\hfil#\hfil}
\cr
\multispan{3}\hrulefill\cr
& Status Register && 0x0\cr
\multispan{3}\hrulefill\cr
& Program Counter High && 0x2\cr
\multispan{3}\hrulefill\cr
& Program Counter Low && 0x4\cr
\multispan{3}\hrulefill\cr
& Format/Vector Offset && 0x6\cr
\multispan{3}\hrulefill\cr
}}\hfil}
@end tex
@end ifset
@ifset use-html
@html
<CENTER>
<TABLE COLS=2 WIDTH="40%" BORDER=2>
<TR><TD ALIGN=center><STRONG>Status Register</STRONG></TD>
<TD ALIGN=center>0x0</TD></TR>
<TR><TD ALIGN=center><STRONG>Program Counter High</STRONG></TD>
<TD ALIGN=center>0x2</TD></TR>
<TR><TD ALIGN=center><STRONG>Program Counter Low</STRONG></TD>
<TD ALIGN=center>0x4</TD></TR>
<TR><TD ALIGN=center><STRONG>Format/Vector Offset</STRONG></TD>
<TD ALIGN=center>0x6</TD></TR>
</TABLE>
</CENTER>
@end html
@end ifset
@subsection Interrupt Levels
Eight levels (0-7) of interrupt priorities are
supported by XXX 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
XXX family only supports eight. RTEMS interrupt levels 0
through 7 directly correspond to XXX interrupt levels. All
other RTEMS interrupt levels are undefined and their behavior is
unpredictable.
@subsection Disabling of Interrupts by RTEMS
During the execution of directive calls, critical
sections of code may be executed. When these sections are
encountered, RTEMS disables interrupts to level seven (7) before
the execution of this section and restores them to the previous
level upon completion of the section. RTEMS has been optimized
to insure that interrupts are disabled for less than
RTEMS_MAXIMUM_DISABLE_PERIOD microseconds on a
RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ Mhz XXX with
zero wait states. These numbers will vary based the
number of wait states and processor speed present on the target board.
[NOTE: The maximum period with interrupts disabled is hand calculated. This
calculation was last performed for Release
RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.]
Non-maskable interrupts (NMI) cannot be disabled, and
ISRs which execute at this level MUST NEVER issue RTEMS system
calls. If a directive is invoked, unpredictable results may
occur due to the inability of RTEMS to protect its critical
sections. However, ISRs that make no system calls may safely
execute as non-maskable interrupts.
@subsection Interrupt Stack
RTEMS allocates the interrupt stack from the
Workspace Area. The amount of memory allocated for the
interrupt stack is determined by the interrupt_stack_size field
in the CPU Configuration Table. During the initialization
process, RTEMS will install its interrupt stack.
The XXX port of RTEMS supports a software managed
dedicated interrupt stack on those CPU models which do not
support a separate interrupt stack in hardware.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Default Fatal Error Processing
Upon detection of a fatal error by either the
application or RTEMS the fatal error manager is invoked. The
fatal error manager will invoke the user-supplied fatal error
handlers. If no user-supplied handlers are configured, the
RTEMS provided default fatal error handler is invoked. If the
user-supplied fatal error handlers return to the executive the
default fatal error handler is then invoked. This chapter
describes the precise operations of the default fatal error
handler.
@subsection Default Fatal Error Handler Operations
The default fatal error handler which is invoked by
the @code{rtems_fatal_error_occurred} directive when there is
no user handler configured or the user handler returns control to
RTEMS. The default fatal error handler disables processor interrupts,
places the error code in @b{XXX}, and executes a @code{XXX}
instruction to simulate a halt processor instruction.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Board Support Packages
An RTEMS Board Support Package (BSP) must be designed
to support a particular processor and target board combination.
This chapter presents a discussion of XXX specific BSP
issues. For more information on developing a BSP, refer to the
chapter titled Board Support Packages in the RTEMS
Applications User's Guide.
@subsection System Reset
An RTEMS based application is initiated or
re-initiated when the XXX processor is reset. When the
XXX is reset, the processor performs the following actions:
@itemize @bullet
@item The tracing bits of the status register are cleared to
disable tracing.
@item The supervisor interrupt state is entered by setting the
supervisor (S) bit and clearing the master/interrupt (M) bit of
the status register.
@item The interrupt mask of the status register is set to
level 7 to effectively disable all maskable interrupts.
@item The vector base register (VBR) is set to zero.
@item The cache control register (CACR) is set to zero to
disable and freeze the processor cache.
@item The interrupt stack pointer (ISP) is set to the value
stored at vector 0 (bytes 0-3) of the exception vector table
(EVT).
@item The program counter (PC) is set to the value stored at
vector 1 (bytes 4-7) of the EVT.
@item The processor begins execution at the address stored in
the PC.
@end itemize
@subsection 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 XXX's VBR value. Because interrupts
are enabled automatically by RTEMS as part of the initialize
executive directive, the VBR MUST be set before this directive
is invoked to insure 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 XXX version has the following
specific requirements:
@itemize @bullet
@item Must leave the S bit of the status register set so that
the XXX remains in the supervisor state.
@item Must set the M bit of the status register to remove the
XXX from the interrupt state.
@item 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.
@item Must initialize the XXX's vector table.
@end itemize
Note that the BSP is not responsible for allocating
or installing the interrupt stack. RTEMS does this
automatically as part of initialization. If the BSP does not
install an interrupt stack and -- for whatever reason -- an
interrupt occurs before initialize_executive is invoked, then
the results are unpredictable.
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Processor Dependent Information Table
Any highly processor dependent information required
to describe a processor to RTEMS is provided in the CPU
Dependent Information Table. This table is not required for all
processors supported by RTEMS. This chapter describes the
contents, if any, for a particular processor type.
@subsection CPU Dependent Information Table
The XXX version of the RTEMS CPU Dependent
Information Table contains the information required to interface
a Board Support Package and RTEMS on the XXX. This
information is provided to allow RTEMS to interoperate
effectively with the BSP. The C structure definition is given
here:
@example
@group
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 */
/* XXX CPU family dependent stuff */
@} rtems_cpu_table;
@end group
@end example
@table @code
@item pretasking_hook
is the address of the user provided routine which is invoked
once RTEMS APIs are initialized. This routine will be invoked
before any system tasks are created. Interrupts are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item predriver_hook
is the address of the user provided
routine that is invoked immediately before the
the device drivers and MPCI are initialized. RTEMS
initialization is complete but interrupts and tasking are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item postdriver_hook
is the address of the user provided
routine that is invoked immediately after the
the device drivers and MPCI are initialized. RTEMS
initialization is complete but interrupts and tasking are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item idle_task
is the address of the optional user
provided routine which is used as the system's IDLE task. If
this field is not NULL, then the RTEMS default IDLE task is not
used. This field may be NULL to indicate that the default IDLE
is to be used.
@item do_zero_of_workspace
indicates whether RTEMS should
zero the Workspace as part of its initialization. If set to
TRUE, the Workspace is zeroed. Otherwise, it is not.
@item idle_task_stack_size
is the size of the RTEMS idle task stack in bytes.
If this number is less than MINIMUM_STACK_SIZE, then the
idle task's stack will be MINIMUM_STACK_SIZE in byte.
@item interrupt_stack_size
is the size of the RTEMS
allocated interrupt stack in bytes. This value must be at least
as large as MINIMUM_STACK_SIZE.
@item extra_mpci_receive_server_stack
is the extra stack space allocated for the RTEMS MPCI receive server task
in bytes. The MPCI receive server may invoke nearly all directives and
may require extra stack space on some targets.
@item stack_allocate_hook
is the address of the optional user provided routine which allocates
memory for task stacks. If this hook is not NULL, then a stack_free_hook
must be provided as well.
@item stack_free_hook
is the address of the optional user provided routine which frees
memory for task stacks. If this hook is not NULL, then a stack_allocate_hook
must be provided as well.
@item XXX
is where the CPU family dependent stuff goes.
@end table

1127
doc/cpu_supplement/sparc.t Normal file
View File

File diff suppressed because it is too large Load Diff

888
doc/cpu_supplement/tic4x.t Normal file
View File

@@ -0,0 +1,888 @@
@c
@c COPYRIGHT (c) 1988-1999.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@ifinfo
@end ifinfo
@chapter Texas Instruments C3x/C4x Specific Information
The Real Time Executive for Multiprocessor Systems (RTEMS)
is designed to be portable across multiple processor
architectures. However, the nature of real-time systems makes
it essential that the application designer understand certain
processor dependent implementation details. These processor
dependencies include calling convention, board support package
issues, interrupt processing, exact RTEMS memory requirements,
performance data, header files, and the assembly language
interface to the executive.
This document discusses the Texas Instrument C3x/C4x
architecture dependencies in this port of RTEMS. The C3x/C4x
family has a wide variety of CPU models within it. The following
CPU model numbers could be supported by this port:
@itemize
@item C30 - TMSXXX
@item C31 - TMSXXX
@item C32 - TMSXXX
@item C41 - TMSXXX
@item C44 - TMSXXX
@end itemize
Initiially, this port does not include full support for C4x models.
Primarily, the C4x specific implementations of interrupt flag and
mask management routines have not been completed.
It is highly recommended that the RTEMS application developer obtain
and become familiar with the documentation for the processor being
used as well as the documentation for the family as a whole.
@subheading Architecture Documents
For information on the Texas Instruments C3x/C4x architecture,
refer to the following documents available from VENDOR
(@file{http//www.ti.com/}):
@itemize @bullet
@item @cite{XXX Family Reference, Texas Instruments, PART NUMBER}.
@end itemize
@subheading MODEL SPECIFIC DOCUMENTS
For information on specific processor models and
their associated coprocessors, refer to the following documents:
@itemize @bullet
@item @cite{XXX MODEL Manual, Texas Instruments, PART NUMBER}.
@item @cite{XXX MODEL Manual, Texas Instruments, PART NUMBER}.
@end itemize
@c
@c COPYRIGHT (c) 1988-1999.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section CPU Model Dependent Features
Microprocessors are generally classified into
families with a variety of CPU models or implementations within
that family. Within a processor family, there is a high level
of binary compatibility. This family may be based on either an
architectural specification or on maintaining compatibility with
a popular processor. Recent microprocessor families such as the
SPARC or PowerPC are based on an architectural specification
which is independent or any particular CPU model or
implementation. Older families such as the M68xxx and the iX86
evolved as the manufacturer strived to produce higher
performance processor models which maintained binary
compatibility with older models.
RTEMS takes advantage of the similarity of the
various models within a CPU family. Although the models do vary
in significant ways, the high level of compatibility makes it
possible to share the bulk of the CPU dependent executive code
across the entire family. Each processor family supported by
RTEMS has a list of features which vary between CPU models
within a family. For example, the most common model dependent
feature regardless of CPU family is the presence or absence of a
floating point unit or coprocessor. When defining the list of
features present on a particular CPU model, one simply notes
that floating point hardware is or is not present and defines a
single constant appropriately. Conditional compilation is
utilized to include the appropriate source code for this CPU
model's feature set. It is important to note that this means
that RTEMS is thus compiled using the appropriate feature set
and compilation flags optimal for this CPU model used. The
alternative would be to generate a binary which would execute on
all family members using only the features which were always
present.
This chapter presents the set of features which vary
across the various implementations of the C3x/C4x architecture
that are of importance to rtems.
the set of cpu model feature macros are defined in the file
cpukit/score/cpu/c4x/rtems/score/c4x.h and are based upon
the particular cpu model defined in the bsp's custom configuration
file as well as the compilation command line.
@subsection CPU Model Name
The macro @code{CPU_MODEL_NAME} is a string which designates
the name of this cpu model. for example, for the c32
processor, this macro is set to the string "c32".
@subsection Floating Point Unit
The Texas Instruments C3x/C4x family makes little distinction
between the various cpu registers. Although floating point
operations may only be performed on a subset of the cpu registers,
these same registers may be used for normal integer operations.
as a result of this, this port of rtems makes no distinction
between integer and floating point contexts. The routine
@code{_CPU_Context_switch} saves all of the registers that
comprise a task's context. the routines that initialize,
save, and restore floating point contexts are not present
in this port.
Moreover, there is no floating point context pointer and
the code in @code{_Thread_Dispatch} that manages the
floating point context switching process is disabled
on this port.
This not only simplifies the port, it also speeds up context
switches by reducing the code involved and reduces the code
space footprint of the executive on the Texas Instruments
C3x/C4x.
@c
@c COPYRIGHT (c) 1988-1999.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Calling Conventions
Each high-level language compiler generates
subroutine entry and exit code based upon a set of rules known
as the compiler's calling convention. These rules address the
following issues:
@itemize @bullet
@item register preservation and usage
@item parameter passing
@item call and return mechanism
@end itemize
A compiler's calling convention is of importance when
interfacing to subroutines written in another language either
assembly or high-level. Even when the high-level language and
target processor are the same, different compilers may use
different calling conventions. As a result, calling conventions
are both processor and compiler dependent.
The GNU Compiler Suite follows the same calling conventions
as the Texas Instruments toolset.
@subsection Processor Background
The TI C3x and C4x processors support a simple yet
effective call and return mechanism. A subroutine is invoked
via the branch to subroutine (@code{XXX}) or the jump to subroutine
(@code{XXX}) instructions. These instructions push the return address
on the current stack. The return from subroutine (@code{XXX})
instruction pops the return address off the current stack and
transfers control to that instruction. It is important to
note that the call and return mechanism for the C3x/C4x 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.
XXX other supplements may have "is is".
@subsection Calling Mechanism
All subroutines are invoked using either a @code{XXX}
or @code{XXX} instruction and return to the user application via the
@code{XXX} instruction.
@subsection Register Usage
XXX
As discussed above, the @code{XXX} and @code{XXX} instructions do
not automatically save any registers. Subroutines use the registers
@b{D0}, @b{D1}, @b{A0}, and @b{A1} as scratch registers. These registers are
not preserved by subroutines therefore, the contents of
these registers should not be assumed upon return from any subroutine
call including but not limited to an RTEMS directive.
The GNU and Texas Instruments compilers follow the same conventions
for register usage.
@subsection Parameter Passing
Both the GNU and Texas Instruments compilers support two conventions
for passing parameters to subroutines. Arguments may be passed in
memory on the stack or in registers.
@subsubsection Parameters Passed in Memory
When passing parameters on the stack, the calling convention assumes
that arguments are placed on the current stack before the subroutine
is invoked via the @code{XXX} 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
subroutine with three (3) arguments:
@example
@group
push third argument
push second argument
push first argument
invoke subroutine
remove arguments from the stack
@end group
@end example
The arguments to RTEMS are typically pushed onto the
stack using a @code{sti} instruction with a pre-incremented 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 subtracting the size of the
argument list in words from the current stack pointer.
@c XXX XXX instruction .. XXX should be code format.
With the GNU Compiler Suite, parameter passing via the
stack is selected by invoking the compiler with the
@code{-mmemparm XXX} argument. This argument must be
included when linking the application in order to
ensure that support libraries also compiled assuming
parameter passing via the stack are used. The default
parameter passing mechanism is XXX.
When this parameter passing mecahanism is selected, the @code{XXX}
symbol is predefined by the C and C++ compilers
and the @code{XXX} symbol is predefined by the assembler.
This behavior is the same for the GNU and Texas Instruments
toolsets. RTEMS uses these predefines to determine how
parameters are passed in to those C3x/C4x specific routines
that were written in assembly language.
@subsubsection Parameters Passed in Registers
When passing parameters via registers, the calling convention assumes
that the arguments are placed in particular registers based upon
their position and data type before the subroutine is invoked via
the @code{XXX} instruction.
The following pseudo-code illustrates
the typical sequence used to call a subroutine with three (3) arguments:
@example
@group
move third argument to XXX
move second argument to XXX
move first argument to XXX
invoke subroutine
@end group
@end example
With the GNU Compiler Suite, parameter passing via
registers is selected by invoking the compiler with the
@code{-mregparm XXX} argument. This argument must be
included when linking the application in order to
ensure that support libraries also compiled assuming
parameter passing via the stack are used. The default
parameter passing mechanism is XXX.
When this parameter passing mecahanism is selected, the @code{XXX}
symbol is predefined by the C and C++ compilers
and the @code{XXX} symbol is predefined by the assembler.
This behavior is the same for the GNU and Texas Instruments
toolsets. RTEMS uses these predefines to determine how
parameters are passed in to those C3x/C4x specific routines
that were written in assembly language.
@subsection User-Provided Routines
All user-provided routines invoked by RTEMS, such as
user extensions, device drivers, and MPCI routines, must also
adhere to these calling conventions.
@c
@c COPYRIGHT (c) 1988-1999.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Memory Model
A processor may support any combination of memory
models ranging from pure physical addressing to complex demand
paged virtual memory systems. RTEMS supports a flat memory
model which ranges contiguously over the processor's allowable
address space. RTEMS does not support segmentation or virtual
memory of any kind. The appropriate memory model for RTEMS
provided by the targeted processor and related characteristics
of that model are described in this chapter.
@subsection Byte Addressable versus Word Addressable
Processor in the Texas Instruments C3x/C4x family are
word addressable. This is in sharp contrast to CISC and
RISC processors that are typically byte addressable. In a word
addressable architecture, each address points not to an
8-bit byte or octet but to 32 bits.
On first glance, byte versus word addressability does not
sound like a problem but in fact, this issue can result in
subtle problems in high-level language software that is ported
to a word addressable processor family. The following is a
list of the commonly encountered problems:
@table @b
@item String Optimizations
Although each character in a string occupies a single address just
as it does on a byte addressable CPU, each character occupies
32 rather than 8 bits. The most significant 24 bytes are
of each address are ignored. This in and of itself does not
cause problems but it violates the assumption that two
adjacent characters in a string have no intervening bits.
This assumption is often implicit in string and memory comparison
routines that are optimized to compare 4 adjacent characters
with a word oriented operation. This optimization is
invalid on word addressable processors.
@item Sizeof
The C operation @code{sizeof} returns very different results
on the C3x/C4x than on traditional RISC/CISC processors.
The @code{sizeof(char)}, @code{sizeof(short)}, and @code{sizeof(int)}
are all 1 since each occupies a single addressable unit that is
thirty-two bits wide. On most thirty-two bit processors,
@code{sizeof(char} is one, @code{sizeof(short)} is two,
and @code{sizeof(int)} is four. Just as software makes assumptions
about the sizes of the primitive data types has problems
when ported to a sixty-four bit architecture, these same
assumptions cause problems on the C3x/C4x.
@item Alignment
Since each addressable unit is thirty-two bit wide, there
are no alignment restrictions. The native integer type
need only be aligned on a "one unit" boundary not a "four
unit" boundary as on numerous other processors.
@end table
@subsection Flat Memory Model
XXX check actual bits on the various processor families.
The XXX 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.
@subsection Compiler Memory Models
The Texas Instruments C3x/C4x processors include a Data Page
(@code{dp}) register that logically is a base address. The
@code{dp} register allows the use of shorter offsets in
instructions. Up to 64K words may be addressed using
offsets from the @code{dp} register. In order to address
words not addressable based on the current value of
@code{dp}, the register must be loaded with a different
value.
The @code{dp} register is managed automatically by
the high-level language compilers.
The various compilers for this processor family support
two memory models that manage the @code{dp} register
in very different manners. The large and small memory
models are discussed in the following sections.
NOTE: The C3x/C4x port of RTEMS has been written
so that it should support either memory model.
However, it has only been tested using the
large memory model.
@subsubsection Small Memory Model
The small memory model is the simplest and most
efficient. However, it includes a limitation that
make it inappropriate for numerous applications. The
small memory model assumes that the application needs
to access no more than 64K words. Thus the @code{dp}
register can be loaded at application start time
and never reloaded. Thus the compiler will not
even generate instructions to load the @code{dp}.
This can significantly reduce the code space
required by an application but the application
is limited in the amount of data it can access.
With the GNU Compiler Suite, small memory model is
selected by invoking the compiler with either the
@code{-msmall} or @code{-msmallmemoryXXX} argument.
This argument must be included when linking the application
in order to ensure that support libraries also compiled
for the large memory model are used.
The default memory model is XXX.
When this memory model is selected, the @code{XXX}
symbol is predefined by the C and C++ compilers
and the @code{XXX} symbol is predefined by the assembler.
This behavior is the same for the GNU and Texas Instruments
toolsets. RTEMS uses these predefines to determine the proper handling
of the @code{dp} register in those C3x/C4x specific routines
that were written in assembly language.
@subsubsection Large Memory Model
The large memory model is more complex and less efficient
than the small memory model. However, it removes the
64K uninitialized data restriction from applications.
The @code{dp} register is reloaded automatically
by the compiler each time data is accessed. This leads
to an increase in the code space requirements for the
application but gives it access to much more data space.
With the GNU Compiler Suite, large memory model is
selected by invoking the compiler with either the
@code{-mlarge} or @code{-mlargememoryXXX} argument.
This argument must be included when linking the application
in order to ensure that support libraries also compiled
for the large memory model are used.
The default memory model is XXX.
When this memory model is selected, the @code{XXX}
symbol is predefined by the C and C++ compilers
and the @code{XXX} symbol is predefined by the assembler.
This behavior is the same for the GNU and Texas Instruments
toolsets. RTEMS uses these predefines to determine the proper handling
of the @code{dp} register in those C3x/C4x specific routines
that were written in assembly language.
@c
@c Interrupt Stack Frame Picture
@c
@c COPYRIGHT (c) 1988-1999.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Interrupt Processing
Different types of processors respond to the
occurrence of an interrupt in its own unique fashion. In
addition, each processor type provides a control mechanism to
allow for the proper handling of an interrupt. The processor
dependent response to the interrupt modifies the current
execution state and results in a change in the execution stream.
Most processors require that an interrupt handler utilize some
special control mechanisms to return to the normal processing
stream. Although RTEMS hides many of the processor dependent
details of interrupt processing, it is important to understand
how the RTEMS interrupt manager is mapped onto the processor's
unique architecture. Discussed in this chapter are the XXX's
interrupt response and control mechanisms as they pertain to
RTEMS.
@subsection Vectoring of an Interrupt Handler
Depending on whether or not the particular CPU
supports a separate interrupt stack, the XXX family has two
different interrupt handling models.
@subsubsection Models Without Separate Interrupt Stacks
Upon receipt of an interrupt the XXX family
members without separate interrupt stacks automatically perform
the following actions:
@itemize @bullet
@item To Be Written
@end itemize
@subsubsection Models With Separate Interrupt Stacks
Upon receipt of an interrupt the XXX family
members with separate interrupt stacks automatically perform the
following actions:
@itemize @bullet
@item saves the current status register (SR),
@item clears the master/interrupt (M) bit of the SR to
indicate the switch from master state to interrupt state,
@item sets the privilege mode to supervisor,
@item suppresses tracing,
@item sets the interrupt mask level equal to the level of the
interrupt being serviced,
@item 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,
@item 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.
@end itemize
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 following shows the Interrupt Stack Frame for
XXX CPU models with separate interrupt stacks:
@ifset use-ascii
@example
@group
+----------------------+
| Status Register | 0x0
+----------------------+
| Program Counter High | 0x2
+----------------------+
| Program Counter Low | 0x4
+----------------------+
| Format/Vector Offset | 0x6
+----------------------+
@end group
@end example
@end ifset
@ifset use-tex
@sp 1
@tex
\centerline{\vbox{\offinterlineskip\halign{
\strut\vrule#&
\hbox to 2.00in{\enskip\hfil#\hfil}&
\vrule#&
\hbox to 0.50in{\enskip\hfil#\hfil}
\cr
\multispan{3}\hrulefill\cr
& Status Register && 0x0\cr
\multispan{3}\hrulefill\cr
& Program Counter High && 0x2\cr
\multispan{3}\hrulefill\cr
& Program Counter Low && 0x4\cr
\multispan{3}\hrulefill\cr
& Format/Vector Offset && 0x6\cr
\multispan{3}\hrulefill\cr
}}\hfil}
@end tex
@end ifset
@ifset use-html
@html
<CENTER>
<TABLE COLS=2 WIDTH="40%" BORDER=2>
<TR><TD ALIGN=center><STRONG>Status Register</STRONG></TD>
<TD ALIGN=center>0x0</TD></TR>
<TR><TD ALIGN=center><STRONG>Program Counter High</STRONG></TD>
<TD ALIGN=center>0x2</TD></TR>
<TR><TD ALIGN=center><STRONG>Program Counter Low</STRONG></TD>
<TD ALIGN=center>0x4</TD></TR>
<TR><TD ALIGN=center><STRONG>Format/Vector Offset</STRONG></TD>
<TD ALIGN=center>0x6</TD></TR>
</TABLE>
</CENTER>
@end html
@end ifset
@subsection Interrupt Levels
Eight levels (0-7) of interrupt priorities are
supported by XXX 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
XXX family only supports eight. RTEMS interrupt levels 0
through 7 directly correspond to XXX interrupt levels. All
other RTEMS interrupt levels are undefined and their behavior is
unpredictable.
@subsection Disabling of Interrupts by RTEMS
During the execution of directive calls, critical
sections of code may be executed. When these sections are
encountered, RTEMS disables interrupts to level seven (7) before
the execution of this section and restores them to the previous
level upon completion of the section. RTEMS has been optimized
to insure that interrupts are disabled for less than
RTEMS_MAXIMUM_DISABLE_PERIOD microseconds on a
RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ Mhz XXX with
zero wait states. These numbers will vary based the
number of wait states and processor speed present on the target board.
[NOTE: The maximum period with interrupts disabled is hand calculated. This
calculation was last performed for Release
RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.]
Non-maskable interrupts (NMI) cannot be disabled, and
ISRs which execute at this level MUST NEVER issue RTEMS system
calls. If a directive is invoked, unpredictable results may
occur due to the inability of RTEMS to protect its critical
sections. However, ISRs that make no system calls may safely
execute as non-maskable interrupts.
@subsection Interrupt Stack
RTEMS allocates the interrupt stack from the
Workspace Area. The amount of memory allocated for the
interrupt stack is determined by the interrupt_stack_size field
in the CPU Configuration Table. During the initialization
process, RTEMS will install its interrupt stack.
The XXX port of RTEMS supports a software managed
dedicated interrupt stack on those CPU models which do not
support a separate interrupt stack in hardware.
@c
@c COPYRIGHT (c) 1988-1999.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Default Fatal Error Processing
Upon detection of a fatal error by either the
application or RTEMS the fatal error manager is invoked. The
fatal error manager will invoke the user-supplied fatal error
handlers. If no user-supplied handlers are configured, the
RTEMS provided default fatal error handler is invoked. If the
user-supplied fatal error handlers return to the executive the
default fatal error handler is then invoked. This chapter
describes the precise operations of the default fatal error
handler.
@subsection Default Fatal Error Handler Operations
The default fatal error handler which is invoked by
the @code{rtems_fatal_error_occurred} directive when there is
no user handler configured or the user handler returns control to
RTEMS. The default fatal error handler disables processor interrupts,
places the error code in @b{XXX}, and executes a @code{XXX}
instruction to simulate a halt processor instruction.
@c
@c COPYRIGHT (c) 1988-1999.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Board Support Packages
An RTEMS Board Support Package (BSP) must be designed
to support a particular processor and target board combination.
This chapter presents a discussion of XXX specific BSP
issues. For more information on developing a BSP, refer to the
chapter titled Board Support Packages in the RTEMS
Applications User's Guide.
@subsection System Reset
An RTEMS based application is initiated or
re-initiated when the XXX processor is reset. When the
XXX is reset, the processor performs the following actions:
@itemize @bullet
@item The tracing bits of the status register are cleared to
disable tracing.
@item The supervisor interrupt state is entered by setting the
supervisor (S) bit and clearing the master/interrupt (M) bit of
the status register.
@item The interrupt mask of the status register is set to
level 7 to effectively disable all maskable interrupts.
@item The vector base register (VBR) is set to zero.
@item The cache control register (CACR) is set to zero to
disable and freeze the processor cache.
@item The interrupt stack pointer (ISP) is set to the value
stored at vector 0 (bytes 0-3) of the exception vector table
(EVT).
@item The program counter (PC) is set to the value stored at
vector 1 (bytes 4-7) of the EVT.
@item The processor begins execution at the address stored in
the PC.
@end itemize
@subsection 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 XXX's VBR value. Because interrupts
are enabled automatically by RTEMS as part of the initialize
executive directive, the VBR MUST be set before this directive
is invoked to insure 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 XXX version has the following
specific requirements:
@itemize @bullet
@item Must leave the S bit of the status register set so that
the XXX remains in the supervisor state.
@item Must set the M bit of the status register to remove the
XXX from the interrupt state.
@item 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.
@item Must initialize the XXX's vector table.
@end itemize
Note that the BSP is not responsible for allocating
or installing the interrupt stack. RTEMS does this
automatically as part of initialization. If the BSP does not
install an interrupt stack and -- for whatever reason -- an
interrupt occurs before initialize_executive is invoked, then
the results are unpredictable.
@c
@c COPYRIGHT (c) 1988-1999.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@section Processor Dependent Information Table
Any highly processor dependent information required
to describe a processor to RTEMS is provided in the CPU
Dependent Information Table. This table is not required for all
processors supported by RTEMS. This chapter describes the
contents, if any, for a particular processor type.
@subsection CPU Dependent Information Table
The XXX version of the RTEMS CPU Dependent
Information Table contains the information required to interface
a Board Support Package and RTEMS on the XXX. This
information is provided to allow RTEMS to interoperate
effectively with the BSP. The C structure definition is given
here:
@example
@group
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 */
/* XXX CPU family dependent stuff */
@} rtems_cpu_table;
@end group
@end example
@table @code
@item pretasking_hook
is the address of the user provided routine which is invoked
once RTEMS APIs are initialized. This routine will be invoked
before any system tasks are created. Interrupts are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item predriver_hook
is the address of the user provided
routine that is invoked immediately before the
the device drivers and MPCI are initialized. RTEMS
initialization is complete but interrupts and tasking are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item postdriver_hook
is the address of the user provided
routine that is invoked immediately after the
the device drivers and MPCI are initialized. RTEMS
initialization is complete but interrupts and tasking are disabled.
This field may be NULL to indicate that the hook is not utilized.
@item idle_task
is the address of the optional user
provided routine which is used as the system's IDLE task. If
this field is not NULL, then the RTEMS default IDLE task is not
used. This field may be NULL to indicate that the default IDLE
is to be used.
@item do_zero_of_workspace
indicates whether RTEMS should
zero the Workspace as part of its initialization. If set to
TRUE, the Workspace is zeroed. Otherwise, it is not.
@item idle_task_stack_size
is the size of the RTEMS idle task stack in bytes.
If this number is less than MINIMUM_STACK_SIZE, then the
idle task's stack will be MINIMUM_STACK_SIZE in byte.
@item interrupt_stack_size
is the size of the RTEMS
allocated interrupt stack in bytes. This value must be at least
as large as MINIMUM_STACK_SIZE.
@item extra_mpci_receive_server_stack
is the extra stack space allocated for the RTEMS MPCI receive server task
in bytes. The MPCI receive server may invoke nearly all directives and
may require extra stack space on some targets.
@item stack_allocate_hook
is the address of the optional user provided routine which allocates
memory for task stacks. If this hook is not NULL, then a stack_free_hook
must be provided as well.
@item stack_free_hook
is the address of the optional user provided routine which frees
memory for task stacks. If this hook is not NULL, then a stack_allocate_hook
must be provided as well.
@item XXX
is where the CPU family dependent stuff goes.
@end table