From 83fb86f32b73942be758c22423c0bfe506fd4ff6 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Wed, 23 Aug 2006 19:11:14 +0000 Subject: 2006-08-23 Joel Sherrill * 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. --- doc/cpu_supplement/.cvsignore | 28 + doc/cpu_supplement/Makefile.am | 81 +++ doc/cpu_supplement/arm.t | 595 +++++++++++++++++++++ doc/cpu_supplement/i386.t | 694 ++++++++++++++++++++++++ doc/cpu_supplement/m68k.t | 773 +++++++++++++++++++++++++++ doc/cpu_supplement/mips.t | 677 +++++++++++++++++++++++ doc/cpu_supplement/powerpc.t | 1043 ++++++++++++++++++++++++++++++++++++ doc/cpu_supplement/preface.texi | 25 + doc/cpu_supplement/sh.t | 685 ++++++++++++++++++++++++ doc/cpu_supplement/sparc.t | 1127 +++++++++++++++++++++++++++++++++++++++ doc/cpu_supplement/tic4x.t | 888 ++++++++++++++++++++++++++++++ 11 files changed, 6616 insertions(+) create mode 100644 doc/cpu_supplement/.cvsignore create mode 100644 doc/cpu_supplement/Makefile.am create mode 100644 doc/cpu_supplement/arm.t create mode 100644 doc/cpu_supplement/i386.t create mode 100644 doc/cpu_supplement/m68k.t create mode 100644 doc/cpu_supplement/mips.t create mode 100644 doc/cpu_supplement/powerpc.t create mode 100644 doc/cpu_supplement/preface.texi create mode 100644 doc/cpu_supplement/sh.t create mode 100644 doc/cpu_supplement/sparc.t create mode 100644 doc/cpu_supplement/tic4x.t (limited to 'doc/cpu_supplement') diff --git a/doc/cpu_supplement/.cvsignore b/doc/cpu_supplement/.cvsignore new file mode 100644 index 0000000000..19d01d9c94 --- /dev/null +++ b/doc/cpu_supplement/.cvsignore @@ -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 diff --git a/doc/cpu_supplement/Makefile.am b/doc/cpu_supplement/Makefile.am new file mode 100644 index 0000000000..02d5be27af --- /dev/null +++ b/doc/cpu_supplement/Makefile.am @@ -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 + diff --git a/doc/cpu_supplement/arm.t b/doc/cpu_supplement/arm.t new file mode 100644 index 0000000000..91e9f23286 --- /dev/null +++ b/doc/cpu_supplement/arm.t @@ -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 diff --git a/doc/cpu_supplement/i386.t b/doc/cpu_supplement/i386.t new file mode 100644 index 0000000000..1b153dd240 --- /dev/null +++ b/doc/cpu_supplement/i386.t @@ -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 +
+ + + + + + + + +
Old EFLAGS Register0x0
UNUSEDOld CS0x2
Old EIP0x4
+
+@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. + diff --git a/doc/cpu_supplement/m68k.t b/doc/cpu_supplement/m68k.t new file mode 100644 index 0000000000..d684328277 --- /dev/null +++ b/doc/cpu_supplement/m68k.t @@ -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 +
+ + + + + + + + + +
Status Register0x0
Program Counter High0x2
Program Counter Low0x4
Format/Vector Offset0x6
+
+@end html +@end ifset + +@subsection CPU Models Without VBR and RAM at 0 + +This is from a post by Zoltan Kocsi 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 diff --git a/doc/cpu_supplement/mips.t b/doc/cpu_supplement/mips.t new file mode 100644 index 0000000000..2fae46ecc2 --- /dev/null +++ b/doc/cpu_supplement/mips.t @@ -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 +
+ + + + + + + + + +
Status Register0x0
Program Counter High0x2
Program Counter Low0x4
Format/Vector Offset0x6
+
+@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 diff --git a/doc/cpu_supplement/powerpc.t b/doc/cpu_supplement/powerpc.t new file mode 100644 index 0000000000..98828c4eed --- /dev/null +++ b/doc/cpu_supplement/powerpc.t @@ -0,0 +1,1043 @@ +@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 PowerPC 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 PowerPC architecture +dependencies in this port of RTEMS. + +It is highly recommended that the PowerPC RTEMS +application developer obtain and become familiar with the +documentation for the processor being used as well as the +specification for the revision of the PowerPC architecture which +corresponds to that processor. + +@subheading PowerPC Architecture Documents + +For information on the PowerPC architecture, refer to +the following documents available from Motorola and IBM: + +@itemize @bullet + +@item @cite{PowerPC Microprocessor Family: The Programming Environment} +(Motorola Document MPRPPCFPE-01). + +@item @cite{IBM PPC403GB Embedded Controller User's Manual}. + +@item @cite{PoweRisControl MPC500 Family RCPU RISC Central Processing +Unit Reference Manual} (Motorola Document RCPUURM/AD). + +@item @cite{PowerPC 601 RISC Microprocessor User's Manual} +(Motorola Document MPR601UM/AD). + +@item @cite{PowerPC 603 RISC Microprocessor User's Manual} +(Motorola Document MPR603UM/AD). + +@item @cite{PowerPC 603e RISC Microprocessor User's Manual} +(Motorola Document MPR603EUM/AD). + +@item @cite{PowerPC 604 RISC Microprocessor User's Manual} +(Motorola Document MPR604UM/AD). + +@item @cite{PowerPC MPC821 Portable Systems Microprocessor User's Manual} +(Motorola Document MPC821UM/AD). + +@item @cite{PowerQUICC MPC860 User's Manual} (Motorola Document MPC860UM/AD). + + +@end itemize + +Motorola maintains an on-line electronic library for the PowerPC +at the following URL: + +@itemize @code{ } +@item @cite{http://www.mot.com/powerpc/library/library.html} +@end itemize + +This site has a a wealth of information and examples. Many of the +manuals are available from that site in electronic format. + +@subheading PowerPC Processor Simulator Information + +PSIM is a program which emulates the Instruction Set Architecture +of the PowerPC microprocessor family. It is reely available in source +code form under the terms of the GNU General Public License (version +2 or later). PSIM can be integrated with the GNU Debugger (gdb) to +execute and debug PowerPC executables on non-PowerPC hosts. PSIM +supports the addition of user provided device models which can be +used to allow one to develop and debug embedded applications using +the simulator. + +The latest version of PSIM is made available to the public via +anonymous ftp at ftp://ftp.ci.com.au/pub/psim or +ftp://cambridge.cygnus.com/pub/psim. There is also a mailing list +at powerpc-psim@@ci.com.au. + + +@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, 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. + +@subsection CPU Model Feature Flags + +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 section presents the set of features which vary +across PowerPC implementations and are of importance to RTEMS. +The set of CPU model feature macros are defined in the file +cpukit/score/cpu/ppc/ppc.h based upon the particular CPU +model defined on the compilation command line. + +@subsubsection CPU Model Name + +The macro CPU_MODEL_NAME is a string which designates +the name of this CPU model. For example, for the PowerPC 603e +model, this macro is set to the string "PowerPC 603e". + +@subsubsection Floating Point Unit + +The macro PPC_HAS_FPU is set to 1 to indicate that this CPU model +has a hardware floating point unit and 0 otherwise. + +@subsubsection Alignment + +The macro PPC_ALIGNMENT is set to the PowerPC model's worst case alignment +requirement for data types on a byte boundary. This value is used +to derive the alignment restrictions for memory allocated from +regions and partitions. + +@subsubsection Cache Alignment + +The macro PPC_CACHE_ALIGNMENT is set to the line size of the cache. It is +used to align the entry point of critical routines so that as much code +as possible can be retrieved with the initial read into cache. This +is done for the interrupt handler as well as the context switch routines. + +In addition, the "shortcut" data structure used by the PowerPC implementation +to ease access to data elements frequently accessed by RTEMS routines +implemented in assembly language is aligned using this value. + +@subsubsection Maximum Interrupts + +The macro PPC_INTERRUPT_MAX is set to the number of exception sources +supported by this PowerPC model. + +@subsubsection Has Double Precision Floating Point + +The macro PPC_HAS_DOUBLE is set to 1 to indicate that the PowerPC model +has support for double precision floating point numbers. This is +important because the floating point registers need only be four bytes +wide (not eight) if double precision is not supported. + +@subsubsection Critical Interrupts + +The macro PPC_HAS_RFCI is set to 1 to indicate that the PowerPC model +has the Critical Interrupt capability as defined by the IBM 403 models. + +@subsubsection Use Multiword Load/Store Instructions + +The macro PPC_USE_MULTIPLE is set to 1 to indicate that multiword load and +store instructions should be used to perform context switch operations. +The relative efficiency of multiword load and store instructions versus +an equivalent set of single word load and store instructions varies based +upon the PowerPC model. + +@subsubsection Instruction Cache Size + +The macro PPC_I_CACHE is set to the size in bytes of the instruction cache. + +@subsubsection Data Cache Size + +The macro PPC_D_CACHE is set to the size in bytes of the data cache. + +@subsubsection Debug Model + +The macro PPC_DEBUG_MODEL is set to indicate the debug support features +present in this CPU model. The following debug support feature sets +are currently supported: + +@table @b + +@item @code{PPC_DEBUG_MODEL_STANDARD} +indicates that the single-step trace enable (SE) and branch trace +enable (BE) bits in the MSR are supported by this CPU model. + +@item @code{PPC_DEBUG_MODEL_SINGLE_STEP_ONLY} +indicates that only the single-step trace enable (SE) bit in the MSR +is supported by this CPU model. + +@item @code{PPC_DEBUG_MODEL_IBM4xx} +indicates that the debug exception enable (DE) bit in the MSR is supported +by this CPU model. At this time, this particular debug feature set +has only been seen in the IBM 4xx series. + +@end table + +@subsubsection Low Power Model + +The macro PPC_LOW_POWER_MODE is set to indicate the low power model +supported by this CPU model. The following low power modes are currently +supported. + +@table @b + +@item @code{PPC_LOW_POWER_MODE_NONE} +indicates that this CPU model has no low power mode support. + +@item @code{PPC_LOW_POWER_MODE_STANDARD} +indicates that this CPU model follows the low power model defined for +the PPC603e. + +@end table +@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. + +RTEMS supports the Embedded Application Binary Interface (EABI) +calling convention. Documentation for EABI is available by sending +a message with a subject line of "EABI" to eabi@@goth.sis.mot.com. + +@subsection Programming Model + +This section discusses the programming model for the +PowerPC architecture. + +@subsubsection Non-Floating Point Registers + +The PowerPC architecture defines thirty-two non-floating point registers +directly visible to the programmer. In thirty-two bit implementations, each +register is thirty-two bits wide. In sixty-four bit implementations, each +register is sixty-four bits wide. + +These registers are referred to as @code{gpr0} to @code{gpr31}. + +Some of the registers serve defined roles in the EABI programming model. +The following table describes the role of each of these registers: + +@ifset use-ascii +@example +@group + +---------------+----------------+------------------------------+ + | Register Name | Alternate Name | Description | + +---------------+----------------+------------------------------+ + | r1 | sp | stack pointer | + +---------------+----------------+------------------------------+ + | | | global pointer to the Small | + | r2 | na | Constant Area (SDA2) | + +---------------+----------------+------------------------------+ + | r3 - r12 | na | parameter and result passing | + +---------------+----------------+------------------------------+ + | | | global pointer to the Small | + | r13 | na | Data Area (SDA) | + +---------------+----------------+------------------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 2.50in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +&\bf Register Name &&\bf Alternate Names&&\bf Description&\cr\noalign{\hrule} +&r1&&sp&&stack pointer&\cr\noalign{\hrule} +&r2&&NA&&global pointer to the Small&\cr +&&&&&Constant Area (SDA2)&\cr\noalign{\hrule} +&r3 - r12&&NA&¶meter and result passing&\cr\noalign{\hrule} +&r13&&NA&&global pointer to the Small&\cr +&&&&&Data Area (SDA2)&\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
+ + + + + + + + + + + + + + + + +
Register NameAlternate NameDescription
r1spstack pointer
r2naglobal pointer to the Small Constant Area (SDA2)
r3 - r12NAparameter and result passing
r13NAglobal pointer to the Small Data Area (SDA)
+
+@end html +@end ifset + + +@subsubsection Floating Point Registers + +The PowerPC architecture includes thirty-two, sixty-four bit +floating point registers. All PowerPC floating point instructions +interpret these registers as 32 double precision floating point registers, +regardless of whether the processor has 64-bit or 32-bit implementation. + +The floating point status and control register (fpscr) records exceptions +and the type of result generated by floating-point operations. +Additionally, it controls the rounding mode of operations and allows the +reporting of floating exceptions to be enabled or disabled. + +@subsubsection Special Registers + +The PowerPC architecture includes a number of special registers +which are critical to the programming model: + +@table @b + +@item Machine State Register + +The MSR contains the processor mode, power management mode, endian mode, +exception information, privilege level, floating point available and +floating point excepiton mode, address translation information and +the exception prefix. + +@item Link Register + +The LR contains the return address after a function call. This register +must be saved before a subsequent subroutine call can be made. The +use of this register is discussed further in the @b{Call and Return +Mechanism} section below. + +@item Count Register + +The CTR contains the iteration variable for some loops. It may also be used +for indirect function calls and jumps. + +@end table + +@subsection Call and Return Mechanism + +The PowerPC architecture supports a simple yet effective call +and return mechanism. A subroutine is invoked +via the "branch and link" (@code{bl}) and +"brank and link absolute" (@code{bla}) +instructions. This instructions place the return address +in the Link Register (LR). The callee returns to the caller by +executing a "branch unconditional to the link register" (@code{blr}) +instruction. Thus the callee returns to the caller via a jump +to the return address which is stored in the LR. + +The previous contents of the LR are not automatically saved +by either the @code{bl} or @code{bla}. It is the responsibility +of the callee to save the contents of the LR before invoking +another subroutine. If the callee invokes another subroutine, +it must restore the LR before executing the @code{blr} instruction +to return to the caller. + +It is important to note that the PowerPC subroutine +call and return mechanism does not automatically save and +restore any registers. + +The LR may be accessed as special purpose register 8 (@code{SPR8}) using the +"move from special register" (@code{mfspr}) and +"move to special register" (@code{mtspr}) instructions. + +@subsection Calling Mechanism + +All RTEMS directives are invoked using the regular +PowerPC EABI calling convention via the @code{bl} or +@code{bla} instructions. + +@subsection Register Usage + +As discussed above, the call instruction does not +automatically save any registers. It is the responsibility +of the callee to save and restore any registers which must be preserved +across subroutine calls. The callee is responsible for saving +callee-preserved registers to the program stack and restoring them +before returning to the caller. + +@subsection Parameter Passing + +RTEMS assumes that arguments are placed in the +general purpose registers with the first argument in +register 3 (@code{r3}), the second argument in general purpose +register 4 (@code{r4}), and so forth until the seventh +argument is in general purpose register 10 (@code{r10}). +If there are more than seven arguments, then subsequent arguments +are placed on the program stack. The following pseudo-code +illustrates the typical sequence used to call a RTEMS directive +with three (3) arguments: + +@example +load third argument into r5 +load second argument into r4 +load first argument into r3 +invoke directive +@end example + +@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 same 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 PowerPC architecture supports a variety of memory models. +RTEMS supports the PowerPC using a flat memory model with +paging disabled. In this mode, the PowerPC automatically +converts every address from a logical to a physical address +each time it is used. The PowerPC uses information provided +in the Block Address Translation (BAT) to convert these addresses. + +Implementations of the PowerPC architecture may be thirty-two or sixty-four bit. +The PowerPC architecture supports a flat thirty-two or sixty-four bit address +space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4 +gigabytes) in thirty-two bit implementations or to 0xFFFFFFFFFFFFFFFF +in sixty-four bit implementations. Each address is represented +by either a thirty-two bit or sixty-four bit value and is byte addressable. +The address may be used to reference a single byte, half-word +(2-bytes), word (4 bytes), or in sixty-four bit implementations a +doubleword (8 bytes). Memory accesses within the address space are +performed in big or little endian fashion by the PowerPC based +upon the current setting of the Little-endian mode enable bit (LE) +in the Machine State Register (MSR). While the processor is in +big endian mode, memory accesses which are not properly aligned +generate an "alignment exception" (vector offset 0x00600). In +little endian mode, the PowerPC architecture does not require +the processor to generate alignment exceptions. + +The following table lists the alignment requirements for a variety +of data accesses: + +@ifset use-ascii +@example +@group + +--------------+-----------------------+ + | Data Type | Alignment Requirement | + +--------------+-----------------------+ + | byte | 1 | + | half-word | 2 | + | word | 4 | + | doubleword | 8 | + +--------------+-----------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +&\bf Data Type &&\bf Alignment Requirement&\cr\noalign{\hrule} +&byte&&1&\cr\noalign{\hrule} +&half-word&&2&\cr\noalign{\hrule} +&word&&4&\cr\noalign{\hrule} +&doubleword&&8&\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
+ + + + + + + + + + + +
Data TypeAlignment Requirement
byte1
half-word2
word4
doubleword8
+
+@end html +@end ifset + +Doubleword load and store operations are only available in +PowerPC CPU models which are sixty-four bit implementations. + +RTEMS does not directly support any PowerPC Memory Management +Units, therefore, virtual memory or segmentation systems +involving the PowerPC are not supported. + +@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 PowerPC's +interrupt response and control mechanisms as they pertain to +RTEMS. + +RTEMS and associated documentation uses the terms +interrupt and vector. In the PowerPC architecture, these terms +correspond to exception and exception handler, respectively. The terms will +be used interchangeably in this manual. + +@subsection Synchronous Versus Asynchronous Exceptions + +In the PowerPC architecture exceptions can be either precise or +imprecise and either synchronous or asynchronous. Asynchronous +exceptions occur when an external event interrupts the processor. +Synchronous exceptions are caused by the actions of an +instruction. During an exception SRR0 is used to calculate where +instruction processing should resume. All instructions prior to +the resume instruction will have completed execution. SRR1 is used to +store the machine status. + +There are two asynchronous nonmaskable, highest-priority exceptions +system reset and machine check. There are two asynchrononous maskable +low-priority exceptions external interrupt and decrementer. Nonmaskable +execptions are never delayed, therefore if two nonmaskable, asynchronous +exceptions occur in immediate succession, the state information saved by +the first exception may be overwritten when the subsequent exception occurs. + +The PowerPC arcitecure defines one imprecise exception, the imprecise +floating point enabled exception. All other synchronous exceptions are +precise. The synchronization occuring during asynchronous precise +exceptions conforms to the requirements for context synchronization. + +@subsection Vectoring of Interrupt Handler + +Upon determining that an exception can be taken the PowerPC automatically +performs the following actions: + +@itemize @bullet +@item an instruction address is loaded into SRR0 + +@item bits 33-36 and 42-47 of SRR1 are loaded with information +specific to the exception. + +@item bits 0-32, 37-41, and 48-63 of SRR1 are loaded with corresponding +bits from the MSR. + +@item the MSR is set based upon the exception type. + +@item instruction fetch and execution resumes, using the new MSR value, at a location specific to the execption type. + +@end itemize + +If the interrupt handler was installed as an RTEMS +interrupt handler, then upon receipt of the interrupt, the +processor passes control to the RTEMS interrupt handler which +performs the following actions: + +@itemize @bullet +@item saves the state of the interrupted task on it's stack, + +@item saves all registers which are not normally preserved +by the calling sequence so the user's interrupt service +routine can be written in a high-level language. + +@item if this is the outermost (i.e. non-nested) interrupt, +then the RTEMS interrupt handler switches from the current stack +to the interrupt stack, + +@item enables exceptions, + +@item invokes the vectors to a user interrupt service routine (ISR). +@end itemize + +Asynchronous interrupts are ignored while exceptions are +disabled. Synchronous interrupts which occur while are +disabled result in the CPU being forced into an error mode. + +A nested interrupt is processed similarly with the +exception that the current stack need not be switched to the +interrupt stack. + +@subsection Interrupt Levels + +The PowerPC architecture supports only a single external +asynchronous interrupt source. This interrupt source +may be enabled and disabled via the External Interrupt Enable (EE) +bit in the Machine State Register (MSR). Thus only two level (enabled +and disabled) of external device interrupt priorities are +directly supported by the PowerPC architecture. + +Some PowerPC implementations include a Critical Interrupt capability +which is often used to receive interrupts from high priority external +devices. + +The RTEMS interrupt level mapping scheme for the PowerPC is not +a numeric level as on most RTEMS ports. It is a bit mapping in +which the least three significiant bits of the interrupt level +are mapped directly to the enabling of specific interrupt +sources as follows: + +@table @b + +@item Critical Interrupt +Setting bit 0 (the least significant bit) of the interrupt level +enables the Critical Interrupt source, if it is available on this +CPU model. + +@item Machine Check +Setting bit 1 of the interrupt level enables Machine Check execptions. + +@item External Interrupt +Setting bit 2 of the interrupt level enables External Interrupt execptions. + +@end table + +All other bits in the RTEMS task interrupt level are ignored. + +@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 Critical Interrupts, External Interrupts +and Machine Checks 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 PowerPC 603e 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.] + +If a PowerPC implementation provides non-maskable interrupts (NMI) +which cannot be disabled, ISRs which process these interrupts +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 PowerPC architecture does not provide for a +dedicated interrupt stack. Thus by default, exception handlers would +execute on the stack of the RTEMS task which they interrupted. +This artificially inflates the stack requirements for each task +since EVERY task stack would have to include enough space to +account for the worst case interrupt stack requirements in +addition to it's own worst case usage. RTEMS addresses this +problem on the PowerPC by providing a dedicated interrupt stack +managed by software. + +During system initialization, 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. As +part of processing a non-nested interrupt, RTEMS will switch to +the interrupt stack before invoking the installed handler. + + + +@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 places the error code in r3, and + +@item executes a trap instruction which results in a Program Exception. + +@end itemize + +If the Program Exception returns, then the following actions are performed: + +@itemize @bullet + +@item disables all processor exceptions by loading a 0 into the MSR, and + +@item goes into an infinite loop 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 PowerPC 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 PowerPC processor is reset. The PowerPC +architecture defines a Reset Exception, but leaves the +details of the CPU state as implementation specific. Please +refer to the User's Manual for the CPU model in question. + +In general, at power-up the PowerPC begin execution at address +0xFFF00100 in supervisor mode with all exceptions disabled. For +soft resets, the CPU will vector to either 0xFFF00100 or 0x00000100 +depending upon the setting of the Exception Prefix bit in the MSR. +If during a soft reset, a Machine Check Exception occurs, then the +CPU may execute a hard reset. + +@subsection Processor Initialization + +It is the responsibility of the application's +initialization code to initialize the CPU and board +to a quiescent state before invoking the @code{rtems_initialize_executive} +directive. It is recommended that the BSP utilize the @code{predriver_hook} +to install default handlers for all exceptions. These default handlers +may be overwritten as various device drivers and subsystems install +their own exception handlers. Upon completion of RTEMS executive +initialization, all interrupts are enabled. + +If this PowerPC implementation supports on-chip caching +and this is to be utilized, then it should be enabled during the +reset application initialization code. On-chip caching has been +observed to prevent some emulators from working properly, so it +may be necessary to run with caching disabled to use these emulators. + +In addition to the requirements described in the +@b{Board Support Packages} chapter of the RTEMS C +Applications User's Manual for the reset code +which is executed before the call to @code{rtems_initialize_executive}, +the PowrePC version has the following specific requirements: + +@itemize @bullet +@item Must leave the PR bit of the Machine State Register (MSR) set +to 0 so the PowerPC remains in the supervisor state. + +@item Must set stack pointer (sp or r1) such that a minimum stack +size of MINIMUM_STACK_SIZE bytes is provided for the +@code{rtems_initialize_executive} directive. + +@item Must disable all external interrupts (i.e. clear the EI (EE) +bit of the machine state register). + +@item Must enable traps so window overflow and underflow +conditions can be properly handled. + +@item Must initialize the PowerPC's initial Exception Table with default +handlers. + +@end itemize + +@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 PowerPC version of the RTEMS CPU Dependent +Information Table is given by the C structure definition is +shown below: + +@example +typedef struct @{ + void (*pretasking_hook)( void ); + void (*predriver_hook)( void ); + void (*postdriver_hook)( void ); + void (*idle_task)( void ); + boolean do_zero_of_workspace; + unsigned32 idle_task_stack_size; + unsigned32 interrupt_stack_size; + unsigned32 extra_mpci_receive_server_stack; + void * (*stack_allocate_hook)( unsigned32 ); + void (*stack_free_hook)( void* ); + /* end of fields required on all CPUs */ + + unsigned32 clicks_per_usec; /* Timer clicks per microsecond */ + void (*spurious_handler)( + unsigned32 vector, CPU_Interrupt_frame *); + boolean exceptions_in_RAM; /* TRUE if in RAM */ + +#if defined(ppc403) + unsigned32 serial_per_sec; /* Serial clocks per second */ + boolean serial_external_clock; + boolean serial_xon_xoff; + boolean serial_cts_rts; + unsigned32 serial_rate; + unsigned32 timer_average_overhead; /* in ticks */ + unsigned32 timer_least_valid; /* Least valid number from timer */ +#endif +@}; +@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 clicks_per_usec +is the number of decrementer interupts that occur each microsecond. + +@item spurious_handler +is the address of the +routine which is invoked when a spurious interrupt occurs. + +@item exceptions_in_RAM +indicates whether the exception vectors are located in RAM or ROM. If +they are located in RAM dynamic vector installation occurs, otherwise +it does not. + +@item serial_per_sec +is a PPC403 specific field which specifies the number of clock +ticks per second for the PPC403 serial timer. + +@item serial_rate +is a PPC403 specific field which specifies the baud rate for the +PPC403 serial port. + +@item serial_external_clock +is a PPC403 specific field which indicates whether or not to mask in a 0x2 into +the Input/Output Configuration Register (IOCR) during initialization of the +PPC403 console. (NOTE: This bit is defined as "reserved" 6-12?) + +@item serial_xon_xoff +is a PPC403 specific field which indicates whether or not +XON/XOFF flow control is supported for the PPC403 serial port. + +@item serial_cts_rts +is a PPC403 specific field which indicates whether or not to set the +least significant bit of the Input/Output Configuration Register +(IOCR) during initialization of the PPC403 console. (NOTE: This +bit is defined as "reserved" 6-12?) + +@item timer_average_overhead +is a PPC403 specific field which specifies the average number of overhead ticks that occur on the PPC403 timer. + +@item timer_least_valid +is a PPC403 specific field which specifies the maximum valid PPC403 timer value. + +@end table + diff --git a/doc/cpu_supplement/preface.texi b/doc/cpu_supplement/preface.texi new file mode 100644 index 0000000000..75c3e386d9 --- /dev/null +++ b/doc/cpu_supplement/preface.texi @@ -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. diff --git a/doc/cpu_supplement/sh.t b/doc/cpu_supplement/sh.t new file mode 100644 index 0000000000..d3ce913457 --- /dev/null +++ b/doc/cpu_supplement/sh.t @@ -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 +
+ + + + + + + + + +
Status Register0x0
Program Counter High0x2
Program Counter Low0x4
Format/Vector Offset0x6
+
+@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 diff --git a/doc/cpu_supplement/sparc.t b/doc/cpu_supplement/sparc.t new file mode 100644 index 0000000000..c8fc03ba30 --- /dev/null +++ b/doc/cpu_supplement/sparc.t @@ -0,0 +1,1127 @@ +@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 SPARC 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 SPARC architecture +dependencies in this port of RTEMS. Currently, only +implementations of SPARC Version 7 are supported by RTEMS. + +It is highly recommended that the SPARC RTEMS +application developer obtain and become familiar with the +documentation for the processor being used as well as the +specification for the revision of the SPARC architecture which +corresponds to that processor. + +@subheading SPARC Architecture Documents + +For information on the SPARC architecture, refer to +the following documents available from SPARC International, Inc. +(http://www.sparc.com): + +@itemize @bullet +@item SPARC Standard Version 7. + +@item SPARC Standard Version 8. + +@item SPARC Standard Version 9. +@end itemize + +@subheading ERC32 Specific Information + +The European Space Agency's ERC32 is a three chip +computing core implementing a SPARC V7 processor and associated +support circuitry for embedded space applications. The integer +and floating-point units (90C601E & 90C602E) are based on the +Cypress 7C601 and 7C602, with additional error-detection and +recovery functions. The memory controller (MEC) implements +system support functions such as address decoding, memory +interface, DMA interface, UARTs, timers, interrupt control, +write-protection, memory reconfiguration and error-detection. +The core is designed to work at 25MHz, but using space qualified +memories limits the system frequency to around 15 MHz, resulting +in a performance of 10 MIPS and 2 MFLOPS. + +Information on the ERC32 and a number of development +support tools, such as the SPARC Instruction Simulator (SIS), +are freely available on the Internet. The following documents +and SIS are available via anonymous ftp or pointing your web +browser at ftp://ftp.estec.esa.nl/pub/ws/wsd/erc32. + +@itemize @bullet +@item ERC32 System Design Document + +@item MEC Device Specification +@end itemize + +Additionally, the SPARC RISC User's Guide from Matra +MHS documents the functionality of the integer and floating +point units including the instruction set information. To +obtain this document as well as ERC32 components and VHDL models +contact: + +@example +Matra MHS SA +3 Avenue du Centre, BP 309, +78054 St-Quentin-en-Yvelines, +Cedex, France +VOICE: +31-1-30607087 +FAX: +31-1-30640693 +@end example + +Amar Guennon (amar.guennon@@matramhs.fr) is familiar with the ERC32. + +@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. + +@subsection CPU Model Feature Flags + +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 section 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/sparc/sparc.h based upon the particular CPU +model defined on the compilation command line. + +@subsubsection CPU Model Name + +The macro CPU_MODEL_NAME is a string which designates +the name of this CPU model. For example, for the European Space +Agency's ERC32 SPARC model, this macro is set to the string +"erc32". + +@subsubsection Floating Point Unit + +The macro SPARC_HAS_FPU is set to 1 to indicate that +this CPU model has a hardware floating point unit and 0 +otherwise. + +@subsubsection Bitscan Instruction + +The macro SPARC_HAS_BITSCAN is set to 1 to indicate +that this CPU model has the bitscan instruction. For example, +this instruction is supported by the Fujitsu SPARClite family. + +@subsubsection Number of Register Windows + +The macro SPARC_NUMBER_OF_REGISTER_WINDOWS is set to +indicate the number of register window sets implemented by this +CPU model. The SPARC architecture allows a for a maximum of +thirty-two register window sets although most implementations +only include eight. + +@subsubsection Low Power Mode + +The macro SPARC_HAS_LOW_POWER_MODE is set to one to +indicate that this CPU model has a low power mode. If low power +is enabled, then there must be CPU model specific implementation +of the IDLE task in cpukit/score/cpu/sparc/cpu.c. The low +power mode IDLE task should be of the form: + +@example +while ( TRUE ) @{ + enter low power mode +@} +@end example + +The code required to enter low power mode is CPU model specific. + +@subsection CPU Model Implementation Notes + +The ERC32 is a custom SPARC V7 implementation based on the Cypress 601/602 +chipset. This CPU has a number of on-board peripherals and was developed by +the European Space Agency to target space applications. RTEMS currently +provides support for the following peripherals: + +@itemize @bullet +@item UART Channels A and B +@item General Purpose Timer +@item Real Time Clock +@item Watchdog Timer (so it can be disabled) +@item Control Register (so powerdown mode can be enabled) +@item Memory Control Register +@item Interrupt Control +@end itemize + +The General Purpose Timer and Real Time Clock Timer provided with the ERC32 +share the Timer Control Register. Because the Timer Control Register is write +only, we must mirror it in software and insure that writes to one timer do not +alter the current settings and status of the other timer. Routines are +provided in erc32.h which promote the view that the two timers are completely +independent. By exclusively using these routines to access the Timer Control +Register, the application can view the system as having a General Purpose +Timer Control Register and a Real Time Clock Timer Control Register +rather than the single shared value. + +The RTEMS Idle thread take advantage of the low power mode provided by the +ERC32. Low power mode is entered during idle loops and is enabled at +initialization time. +@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 Programming Model + +This section discusses the programming model for the +SPARC architecture. + +@subsubsection Non-Floating Point Registers + +The SPARC architecture defines thirty-two +non-floating point registers directly visible to the programmer. +These are divided into four sets: + +@itemize @bullet +@item input registers + +@item local registers + +@item output registers + +@item global registers +@end itemize + +Each register is referred to by either two or three +names in the SPARC reference manuals. First, the registers are +referred to as r0 through r31 or with the alternate notation +r[0] through r[31]. Second, each register is a member of one of +the four sets listed above. Finally, some registers have an +architecturally defined role in the programming model which +provides an alternate name. The following table describes the +mapping between the 32 registers and the register sets: + +@ifset use-ascii +@example +@group + +-----------------+----------------+------------------+ + | Register Number | Register Names | Description | + +-----------------+----------------+------------------+ + | 0 - 7 | g0 - g7 | Global Registers | + +-----------------+----------------+------------------+ + | 8 - 15 | o0 - o7 | Output Registers | + +-----------------+----------------+------------------+ + | 16 - 23 | l0 - l7 | Local Registers | + +-----------------+----------------+------------------+ + | 24 - 31 | i0 - i7 | Input Registers | + +-----------------+----------------+------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +&\bf Register Number &&\bf Register Names&&\bf Description&\cr\noalign{\hrule} +&0 - 7&&g0 - g7&&Global Registers&\cr\noalign{\hrule} +&8 - 15&&o0 - o7&&Output Registers&\cr\noalign{\hrule} +&16 - 23&&l0 - l7&&Local Registers&\cr\noalign{\hrule} +&24 - 31&&i0 - i7&&Input Registers&\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
+ + + + + + + + + + + + + + + + +
Register NumberRegister NamesDescription
0 - 7g0 - g7Global Registers
8 - 15o0 - o7Output Registers
16 - 23l0 - l7Local Registers
24 - 31i0 - i7Input Registers
+
+@end html +@end ifset + +As mentioned above, some of the registers serve +defined roles in the programming model. The following table +describes the role of each of these registers: + +@ifset use-ascii +@example +@group + +---------------+----------------+----------------------+ + | Register Name | Alternate Name | Description | + +---------------+----------------+----------------------+ + | g0 | na | reads return 0 | + | | | writes are ignored | + +---------------+----------------+----------------------+ + | o6 | sp | stack pointer | + +---------------+----------------+----------------------+ + | i6 | fp | frame pointer | + +---------------+----------------+----------------------+ + | i7 | na | return address | + +---------------+----------------+----------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +&\bf Register Name &&\bf Alternate Names&&\bf Description&\cr\noalign{\hrule} +&g0&&NA&&reads return 0; &\cr +&&&&&writes are ignored&\cr\noalign{\hrule} +&o6&&sp&&stack pointer&\cr\noalign{\hrule} +&i6&&fp&&frame pointer&\cr\noalign{\hrule} +&i7&&NA&&return address&\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
+ + + + + + + + + + + + + + + + +
Register NameAlternate NameDescription
g0NAreads return 0 ; writes are ignored
o6spstack pointer
i6fpframe pointer
i7NAreturn address
+
+@end html +@end ifset + + +@subsubsection Floating Point Registers + +The SPARC V7 architecture includes thirty-two, +thirty-two bit registers. These registers may be viewed as +follows: + +@itemize @bullet +@item 32 single precision floating point or integer registers +(f0, f1, ... f31) + +@item 16 double precision floating point registers (f0, f2, +f4, ... f30) + +@item 8 extended precision floating point registers (f0, f4, +f8, ... f28) +@end itemize + +The floating point status register (fpsr) specifies +the behavior of the floating point unit for rounding, contains +its condition codes, version specification, and trap information. + +A queue of the floating point instructions which have +started execution but not yet completed is maintained. This +queue is needed to support the multiple cycle nature of floating +point operations and to aid floating point exception trap +handlers. Once a floating point exception has been encountered, +the queue is frozen until it is emptied by the trap handler. +The floating point queue is loaded by launching instructions. +It is emptied normally when the floating point completes all +outstanding instructions and by floating point exception +handlers with the store double floating point queue (stdfq) +instruction. + +@subsubsection Special Registers + +The SPARC architecture includes two special registers +which are critical to the programming model: the Processor State +Register (psr) and the Window Invalid Mask (wim). The psr +contains the condition codes, processor interrupt level, trap +enable bit, supervisor mode and previous supervisor mode bits, +version information, floating point unit and coprocessor enable +bits, and the current window pointer (cwp). The cwp field of +the psr and wim register are used to manage the register windows +in the SPARC architecture. The register windows are discussed +in more detail below. + +@subsection Register Windows + +The SPARC architecture includes the concept of +register windows. An overly simplistic way to think of these +windows is to imagine them as being an infinite supply of +"fresh" register sets available for each subroutine to use. In +reality, they are much more complicated. + +The save instruction is used to obtain a new register +window. This instruction decrements the current window pointer, +thus providing a new set of registers for use. This register +set includes eight fresh local registers for use exclusively by +this subroutine. When done with a register set, the restore +instruction increments the current window pointer and the +previous register set is once again available. + +The two primary issues complicating the use of +register windows are that (1) the set of register windows is +finite, and (2) some registers are shared between adjacent +registers windows. + +Because the set of register windows is finite, it is +possible to execute enough save instructions without +corresponding restore's to consume all of the register windows. +This is easily accomplished in a high level language because +each subroutine typically performs a save instruction upon +entry. Thus having a subroutine call depth greater than the +number of register windows will result in a window overflow +condition. The window overflow condition generates a trap which +must be handled in software. The window overflow trap handler +is responsible for saving the contents of the oldest register +window on the program stack. + +Similarly, the subroutines will eventually complete +and begin to perform restore's. If the restore results in the +need for a register window which has previously been written to +memory as part of an overflow, then a window underflow condition +results. Just like the window overflow, the window underflow +condition must be handled in software by a trap handler. The +window underflow trap handler is responsible for reloading the +contents of the register window requested by the restore +instruction from the program stack. + +The Window Invalid Mask (wim) and the Current Window +Pointer (cwp) field in the psr are used in conjunction to manage +the finite set of register windows and detect the window +overflow and underflow conditions. The cwp contains the index +of the register window currently in use. The save instruction +decrements the cwp modulo the number of register windows. +Similarly, the restore instruction increments the cwp modulo the +number of register windows. Each bit in the wim represents +represents whether a register window contains valid information. +The value of 0 indicates the register window is valid and 1 +indicates it is invalid. When a save instruction causes the cwp +to point to a register window which is marked as invalid, a +window overflow condition results. Conversely, the restore +instruction may result in a window underflow condition. + +Other than the assumption that a register window is +always available for trap (i.e. interrupt) handlers, the SPARC +architecture places no limits on the number of register windows +simultaneously marked as invalid (i.e. number of bits set in the +wim). However, RTEMS assumes that only one register window is +marked invalid at a time (i.e. only one bit set in the wim). +This makes the maximum possible number of register windows +available to the user while still meeting the requirement that +window overflow and underflow conditions can be detected. + +The window overflow and window underflow trap +handlers are a critical part of the run-time environment for a +SPARC application. The SPARC architectural specification allows +for the number of register windows to be any power of two less +than or equal to 32. The most common choice for SPARC +implementations appears to be 8 register windows. This results +in the cwp ranging in value from 0 to 7 on most implementations. + + +The second complicating factor is the sharing of +registers between adjacent register windows. While each +register window has its own set of local registers, the input +and output registers are shared between adjacent windows. The +output registers for register window N are the same as the input +registers for register window ((N - 1) modulo RW) where RW is +the number of register windows. An alternative way to think of +this is to remember how parameters are passed to a subroutine on +the SPARC. The caller loads values into what are its output +registers. Then after the callee executes a save instruction, +those parameters are available in its input registers. This is +a very efficient way to pass parameters as no data is actually +moved by the save or restore instructions. + +@subsection Call and Return Mechanism + +The SPARC architecture supports a simple yet +effective call and return mechanism. A subroutine is invoked +via the call (call) instruction. This instruction places the +return address in the caller's output register 7 (o7). After +the callee executes a save instruction, this value is available +in input register 7 (i7) until the corresponding restore +instruction is executed. + +The callee returns to the caller via a jmp to the +return address. There is a delay slot following this +instruction which is commonly used to execute a restore +instruction -- if a register window was allocated by this +subroutine. + +It is important to note that the SPARC subroutine +call and return mechanism does not automatically save and +restore any registers. This is accomplished via the save and +restore instructions which manage the set of registers windows. + +@subsection Calling Mechanism + +All RTEMS directives are invoked using the regular +SPARC calling convention via the call instruction. + +@subsection Register Usage + +As discussed above, the call instruction does not +automatically save any registers. The save and restore +instructions are used to allocate and deallocate register +windows. When a register window is allocated, the new set of +local registers are available for the exclusive use of the +subroutine which allocated this register set. + +@subsection Parameter Passing + +RTEMS assumes that arguments are placed in the +caller's output registers with the first argument in output +register 0 (o0), the second argument in output register 1 (o1), +and so forth. Until the callee executes a save instruction, the +parameters are still visible in the output registers. After the +callee executes a save instruction, the parameters are visible +in the corresponding input registers. The following pseudo-code +illustrates the typical sequence used to call a RTEMS directive +with three (3) arguments: + +@example +load third argument into o2 +load second argument into o1 +load first argument into o0 +invoke directive +@end example + +@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 SPARC architecture 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), word (4 bytes), or doubleword +(8 bytes). Memory accesses within this address space are +performed in big endian fashion by the SPARC. Memory accesses +which are not properly aligned generate a "memory address not +aligned" trap (type number 7). The following table lists the +alignment requirements for a variety of data accesses: + +@ifset use-ascii +@example +@group + +--------------+-----------------------+ + | Data Type | Alignment Requirement | + +--------------+-----------------------+ + | byte | 1 | + | half-word | 2 | + | word | 4 | + | doubleword | 8 | + +--------------+-----------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +&\bf Data Type &&\bf Alignment Requirement&\cr\noalign{\hrule} +&byte&&1&\cr\noalign{\hrule} +&half-word&&2&\cr\noalign{\hrule} +&word&&4&\cr\noalign{\hrule} +&doubleword&&8&\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
+ + + + + + + + + + + +
Data TypeAlignment Requirement
byte1
half-word2
word4
doubleword8
+
+@end html +@end ifset + +Doubleword load and store operations must use a pair +of registers as their source or destination. This pair of +registers must be an adjacent pair of registers with the first +of the pair being even numbered. For example, a valid +destination for a doubleword load might be input registers 0 and +1 (i0 and i1). The pair i1 and i2 would be invalid. [NOTE: +Some assemblers for the SPARC do not generate an error if an odd +numbered register is specified as the beginning register of the +pair. In this case, the assembler assumes that what the +programmer meant was to use the even-odd pair which ends at the +specified register. This may or may not have been a correct +assumption.] + +RTEMS does not support any SPARC Memory Management +Units, therefore, virtual memory or segmentation systems +involving the SPARC are not supported. + +@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 SPARC's +interrupt response and control mechanisms as they pertain to +RTEMS. + +RTEMS and associated documentation uses the terms +interrupt and vector. In the SPARC architecture, these terms +correspond to traps and trap type, respectively. The terms will +be used interchangeably in this manual. + +@subsection Synchronous Versus Asynchronous Traps + +The SPARC architecture includes two classes of traps: +synchronous and asynchronous. Asynchronous traps occur when an +external event interrupts the processor. These traps are not +associated with any instruction executed by the processor and +logically occur between instructions. The instruction currently +in the execute stage of the processor is allowed to complete +although subsequent instructions are annulled. The return +address reported by the processor for asynchronous traps is the +pair of instructions following the current instruction. + +Synchronous traps are caused by the actions of an +instruction. The trap stimulus in this case either occurs +internally to the processor or is from an external signal that +was provoked by the instruction. These traps are taken +immediately and the instruction that caused the trap is aborted +before any state changes occur in the processor itself. The +return address reported by the processor for synchronous traps +is the instruction which caused the trap and the following +instruction. + +@subsection Vectoring of Interrupt Handler + +Upon receipt of an interrupt the SPARC automatically +performs the following actions: + +@itemize @bullet +@item disables traps (sets the ET bit of the psr to 0), + +@item the S bit of the psr is copied into the Previous +Supervisor Mode (PS) bit of the psr, + +@item the cwp is decremented by one (modulo the number of +register windows) to activate a trap window, + +@item the PC and nPC are loaded into local register 1 and 2 +(l0 and l1), + +@item the trap type (tt) field of the Trap Base Register (TBR) +is set to the appropriate value, and + +@item if the trap is not a reset, then the PC is written with +the contents of the TBR and the nPC is written with TBR + 4. If +the trap is a reset, then the PC is set to zero and the nPC is +set to 4. +@end itemize + +Trap processing on the SPARC has two features which +are noticeably different than interrupt processing on other +architectures. First, the value of psr register in effect +immediately before the trap occurred is not explicitly saved. +Instead only reversible alterations are made to it. Second, the +Processor Interrupt Level (pil) is not set to correspond to that +of the interrupt being processed. When a trap occurs, ALL +subsequent traps are disabled. In order to safely invoke a +subroutine during trap handling, traps must be enabled to allow +for the possibility of register window overflow and underflow +traps. + +If the interrupt handler was installed as an RTEMS +interrupt handler, then upon receipt of the interrupt, the +processor passes control to the RTEMS interrupt handler which +performs the following actions: + +@itemize @bullet +@item saves the state of the interrupted task on it's stack, + +@item insures that a register window is available for +subsequent traps, + +@item if this is the outermost (i.e. non-nested) interrupt, +then the RTEMS interrupt handler switches from the current stack +to the interrupt stack, + +@item enables traps, + +@item invokes the vectors to a user interrupt service routine (ISR). +@end itemize + +Asynchronous interrupts are ignored while traps are +disabled. Synchronous traps which occur while traps are +disabled result in the CPU being forced into an error mode. + +A nested interrupt is processed similarly with the +exception that the current stack need not be switched to the +interrupt stack. + +@subsection Traps and Register Windows + +One of the register windows must be reserved at all +times for trap processing. This is critical to the proper +operation of the trap mechanism in the SPARC architecture. It +is the responsibility of the trap handler to insure that there +is a register window available for a subsequent trap before +re-enabling traps. It is likely that any high level language +routines invoked by the trap handler (such as a user-provided +RTEMS interrupt handler) will allocate a new register window. +The save operation could result in a window overflow trap. This +trap cannot be correctly processed unless (1) traps are enabled +and (2) a register window is reserved for traps. Thus, the +RTEMS interrupt handler insures that a register window is +available for subsequent traps before enabling traps and +invoking the user's interrupt handler. + +@subsection Interrupt Levels + +Sixteen levels (0-15) of interrupt priorities are +supported by the SPARC architecture with level fifteen (15) +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 +SPARC only supports sixteen. RTEMS interrupt levels 0 through +15 directly correspond to SPARC processor 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 (15) +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 ERC32 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.] + +[NOTE: It is thought that the length of time at which +the processor interrupt level is elevated to fifteen by RTEMS is +not anywhere near as long as the length of time ALL traps are +disabled as part of the "flush all register windows" operation.] + +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 SPARC architecture does not provide for a +dedicated interrupt stack. Thus by default, trap handlers would +execute on the stack of the RTEMS task which they interrupted. +This artificially inflates the stack requirements for each task +since EVERY task stack would have to include enough space to +account for the worst case interrupt stack requirements in +addition to it's own worst case usage. RTEMS addresses this +problem on the SPARC by providing a dedicated interrupt stack +managed by software. + +During system initialization, 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. As +part of processing a non-nested interrupt, RTEMS will switch to +the interrupt stack before invoking the installed handler. + +@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 15, places the error code in g1, and goes into an infinite +loop 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 SPARC 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 SPARC processor is reset. When the SPARC +is reset, the processor performs the following actions: + +@itemize @bullet +@item the enable trap (ET) of the psr is set to 0 to disable +traps, + +@item the supervisor bit (S) of the psr is set to 1 to enter +supervisor mode, and + +@item the PC is set 0 and the nPC is set to 4. +@end itemize + +The processor then begins to execute the code at +location 0. It is important to note that all fields in the psr +are not explicitly set by the above steps and all other +registers retain their value from the previous execution mode. +This is true even of the Trap Base Register (TBR) whose contents +reflect the last trap which occurred before the reset. + +@subsection Processor Initialization + +It is the responsibility of the application's +initialization code to initialize the TBR and install trap +handlers for at least the register window overflow and register +window underflow conditions. Traps should be enabled before +invoking any subroutines to allow for register window +management. However, interrupts should be disabled by setting +the Processor Interrupt Level (pil) field of the psr to 15. +RTEMS installs it's own Trap Table as part of initialization +which is initialized with the contents of the Trap Table in +place when the @code{rtems_initialize_executive} directive was invoked. +Upon completion of executive initialization, interrupts are +enabled. + +If this SPARC implementation supports on-chip caching +and this 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 @value{LANGUAGE} +Applications User's Manual for the reset code +which is executed before the call to +@code{rtems_initialize_executive}, the SPARC version has the following +specific requirements: + +@itemize @bullet +@item Must leave the S bit of the status register set so that +the SPARC remains in the supervisor state. + +@item Must set stack pointer (sp) such that a minimum stack +size of MINIMUM_STACK_SIZE bytes is provided for the +@code{rtems_initialize_executive} directive. + +@item Must disable all external interrupts (i.e. set the pil +to 15). + +@item Must enable traps so window overflow and underflow +conditions can be properly handled. + +@item Must initialize the SPARC's initial trap table with at +least trap handlers for register window overflow and register +window underflow. +@end itemize + +@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 SPARC version of the RTEMS CPU Dependent +Information Table is given by the C structure definition is +shown below: + +@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 */ + +@} 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. + +@end table + diff --git a/doc/cpu_supplement/tic4x.t b/doc/cpu_supplement/tic4x.t new file mode 100644 index 0000000000..9c276eae5c --- /dev/null +++ b/doc/cpu_supplement/tic4x.t @@ -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 +
+ + + + + + + + + +
Status Register0x0
Program Counter High0x2
Program Counter Low0x4
Format/Vector Offset0x6
+
+@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 -- cgit v1.2.3