+++ /dev/null
-<!-- Copyright (C) 2003 Red Hat, Inc. -->
-<!-- This material may be distributed only subject to the terms -->
-<!-- and conditions set forth in the Open Publication License, v1.0 -->
-<!-- or later (the latest version is presently available at -->
-<!-- http://www.opencontent.org/openpub/). -->
-<!-- Distribution of the work or derivative of the work in any -->
-<!-- standard (paper) book form is prohibited unless prior -->
-<!-- permission is obtained from the copyright holder. -->
-<HTML
-><HEAD
-><TITLE
->Architecture HAL Porting</TITLE
-><meta name="MSSmartTagsPreventParsing" content="TRUE">
-<META
-NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
-"><LINK
-REL="HOME"
-TITLE="eCos Reference Manual"
-HREF="ecos-ref.html"><LINK
-REL="UP"
-TITLE=" Porting Guide"
-HREF="hal-porting-guide.html"><LINK
-REL="PREVIOUS"
-TITLE="Variant HAL Porting"
-HREF="hal-porting-variant.html"><LINK
-REL="NEXT"
-TITLE="Future developments"
-HREF="hal-future-developments.html"></HEAD
-><BODY
-CLASS="SECTION"
-BGCOLOR="#FFFFFF"
-TEXT="#000000"
-LINK="#0000FF"
-VLINK="#840084"
-ALINK="#0000FF"
-><DIV
-CLASS="NAVHEADER"
-><TABLE
-SUMMARY="Header navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TH
-COLSPAN="3"
-ALIGN="center"
->eCos Reference Manual</TH
-></TR
-><TR
-><TD
-WIDTH="10%"
-ALIGN="left"
-VALIGN="bottom"
-><A
-HREF="hal-porting-variant.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
->Chapter 11. Porting Guide</TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
-><A
-HREF="hal-future-developments.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><DIV
-CLASS="SECTION"
-><H1
-CLASS="SECTION"
-><A
-NAME="HAL-PORTING-ARCHITECTURE">Architecture HAL Porting</H1
-><P
->A new architecture HAL is the most complex HAL to write, and it the
-least easily described. Hence this section is presently nothing more
-than a place holder for the future.</P
-><DIV
-CLASS="SECTION"
-><H2
-CLASS="SECTION"
-><A
-NAME="AEN9793">HAL Architecture Porting Process</H2
-><P
->The easiest way to make a new architecture HAL is simply to copy an
-existing architecture HAL of an, if possible, closely matching
-architecture and change all the files to match the new
-architecture. The MIPS architecture HAL should be used if possible, as
-it has the appropriate layout and coding conventions. Other HALs
-may deviate from that norm in various ways.</P
-><DIV
-CLASS="NOTE"
-><BLOCKQUOTE
-CLASS="NOTE"
-><P
-><B
->Note: </B
-> eCos is written for GCC. It requires C and C++
-compiler support as well as a few compiler features introduced during
-eCos development - so compilers older than eCos may not provide these
-features. Note that there is no C++ support for any 8 or 16 bit
-CPUs. Before you can undertake an eCos port, you need the required
-compiler support.</P
-></BLOCKQUOTE
-></DIV
-><P
->The following gives a rough outline of the steps needed to create a
-new architecture HAL. The exact order and set of steps needed will
-vary greatly from architecture to architecture, so a lot of
-flexibility is required. And of course, if the architecture HAL is to
-be tested, it is necessary to do variant and platform ports for the
-initial target simultaneously.</P
-><P
-></P
-><OL
-TYPE="1"
-><LI
-><P
->Make a new directory for the new architecture under the
-<TT
-CLASS="FILENAME"
->hal</TT
-> directory in the source repository. Make an
-<TT
-CLASS="FILENAME"
->arch</TT
-> directory under this and populate this with
-the standard set of package directories.</P
-></LI
-><LI
-><P
->Copy the CDL file from an example HAL changing its name to match the
-new HAL. Edit the file, changing option names as appropriate. Delete
-any options that are specific to the original HAL, and and any new
-options that are necessary for the new architecture. This is likely to
-be a continuing process during the development of the HAL. See <A
-HREF="hal-porting-architecture.html#HAL-PORTING-ARCHITECTURE-CDL"
->the Section called <I
->CDL Requirements</I
-></A
-> for more details.</P
-></LI
-><LI
-><P
->Copy the <TT
-CLASS="FILENAME"
->hal_arch.h</TT
-> file from an example
-HAL. Within this file you need to change or define the following:</P
-><P
-></P
-><UL
-><LI
-><P
->Define the <SPAN
-CLASS="STRUCTNAME"
->HAL_SavedRegisters</SPAN
-> structure. This
-may need to reflect the save order of any group register save/restore
-instructions, the interrupt and exception save and restore formats,
-and the procedure calling conventions. It may also need to cater for
-optional FPUs and other functional units. It can be quite difficult to
-develop a layout that copes with all requirements.</P
-></LI
-><LI
-><P
->Define the bit manipulation routines,
-<TT
-CLASS="LITERAL"
->HAL_LSBIT_INDEX()</TT
-> and
-<TT
-CLASS="LITERAL"
->HAL_MSBIT_INDEX()</TT
->. If the architecture contains
-instructions to perform these, or related, operations, then these
-should be defined as inline assembler fragments. Otherwise make them
-calls to functions.</P
-></LI
-><LI
-><P
->Define <TT
-CLASS="LITERAL"
->HAL_THREAD_INIT_CONTEXT()</TT
->. This initializes
-a restorable CPU context onto a stack pointer so that a later call to
-<TT
-CLASS="LITERAL"
->HAL_THREAD_LOAD_CONTEXT()</TT
-> or
-<TT
-CLASS="LITERAL"
->HAL_THREAD_SWITCH_CONTEXT()</TT
-> will execute it
-correctly. This macro needs to take account of the same optional
-features of the architecture as the definition of
-<SPAN
-CLASS="STRUCTNAME"
->HAL_SavedRegisters</SPAN
->.</P
-></LI
-><LI
-><P
->Define <TT
-CLASS="LITERAL"
->HAL_THREAD_LOAD_CONTEXT()</TT
-> and
-<TT
-CLASS="LITERAL"
->HAL_THREAD_SWITCH_CONTEXT()</TT
->. These should just be
-calls to functions in <TT
-CLASS="FILENAME"
->context.S</TT
->.</P
-></LI
-><LI
-><P
->Define <TT
-CLASS="LITERAL"
->HAL_REORDER_BARRIER()</TT
->. This prevents code
-being moved by the compiler and is necessary in some order-sensitive
-code. This macro is actually defined identically in all architecture,
-so it can just be copied.</P
-></LI
-><LI
-><P
->Define breakpoint support. The macro
-<TT
-CLASS="LITERAL"
->HAL_BREAKPOINT(label)</TT
-> needs to be an inline assembly
-fragment that invokes a breakpoint. The breakpoint instruction should
-be labeled with the <TT
-CLASS="PARAMETER"
-><I
->label</I
-></TT
->
-argument. <TT
-CLASS="LITERAL"
->HAL_BREAKINST</TT
-> and
-<TT
-CLASS="LITERAL"
->HAL_BREAKINST_SIZE</TT
-> define the breakpoint
-instruction for debugging purposes.</P
-></LI
-><LI
-><P
->Define GDB support. GDB views the registers of the target as a linear
-array, with each register having a well defined offset. This array may
-differ from the ordering defined in
-<SPAN
-CLASS="STRUCTNAME"
->HAL_SavedRegisters</SPAN
->. The macros
-<TT
-CLASS="LITERAL"
->HAL_GET_GDB_REGISTERS()</TT
-> and
-<TT
-CLASS="LITERAL"
->HAL_SET_GDB_REGISTERS()</TT
-> translate between the GDB
-array and the <SPAN
-CLASS="STRUCTNAME"
->HAL_SavedRegisters</SPAN
-> structure.
-The <TT
-CLASS="LITERAL"
->HAL_THREAD_GET_SAVED_REGISTERS()</TT
-> translates a
-stack pointer saved by the context switch macros into a pointer to a
-<SPAN
-CLASS="STRUCTNAME"
->HAL_SavedRegisters</SPAN
-> structure. Usually this is
-a one-to-one translation, but this macro allows it to differ if
-necessary.</P
-></LI
-><LI
-><P
->Define long jump support. The type <SPAN
-CLASS="TYPE"
->hal_jmp_buf</SPAN
-> and the
-functions <TT
-CLASS="FUNCTION"
->hal_setjmp()</TT
-> and
-<TT
-CLASS="LITERAL"
->hal_longjmp()</TT
-> provide the underlying implementation
-of the C library <TT
-CLASS="FUNCTION"
->setjmp()</TT
-> and
-<TT
-CLASS="FUNCTION"
->longjmp()</TT
->.</P
-></LI
-><LI
-><P
->Define idle thread action. Generally the macro
-<TT
-CLASS="LITERAL"
->HAL_IDLE_THREAD_ACTION()</TT
-> is defined to call a
-function in <TT
-CLASS="FILENAME"
->hal_misc.c</TT
->.</P
-></LI
-><LI
-><P
->Define stack sizes. The macros
-<TT
-CLASS="LITERAL"
->CYGNUM_HAL_STACK_SIZE_MINIMUM</TT
-> and
-<TT
-CLASS="LITERAL"
->CYGNUM_HAL_STACK_SIZE_TYPICAL</TT
-> should be defined to
-the minimum size for any thread stack and a reasonable default for
-most threads respectively. It is usually best to construct these out
-of component sizes for the CPU save state and procedure call stack
-usage. These definitions should not use anything other than numerical
-values since they can be used from assembly code in some HALs.</P
-></LI
-><LI
-><P
->Define memory access macros. These macros provide translation between
-cached and uncached and physical memory spaces. They usually consist
-of masking out bits of the supplied address and ORing in alternative
-address bits.</P
-></LI
-><LI
-><P
->Define global pointer save/restore macros. These really only need
-defining if the calling conventions of the architecture require a
-global pointer (as does the MIPS architecture), they may be empty
-otherwise. If it is necessary to define these, then take a look at the
-MIPS implementation for an example.</P
-></LI
-></UL
-></LI
-><LI
-><P
->Copy <TT
-CLASS="FILENAME"
->hal_intr.h</TT
-> from an example HAL. Within this
-file you should change or define the following:</P
-><P
-></P
-><UL
-><LI
-><P
->Define the exception vectors. These should be detailed in the
-architecture specification. Essentially for each exception entry point
-defined by the architecture there should be an entry in the VSR
-table. The offsets of these VSR table entries should be defined here
-by <TT
-CLASS="LITERAL"
->CYGNUM_HAL_VECTOR_*</TT
-> definitions. The size of the
-VSR table also needs to be defined here.</P
-></LI
-><LI
-><P
->Map any hardware exceptions to standard names. There is a group of
-exception vector name of the form
-<TT
-CLASS="LITERAL"
->CYGNUM_HAL_EXCEPTION_*</TT
-> that define a wide variety
-of possible exceptions that many architectures raise. Generic code
-detects whether the architecture can raise a given exception by
-testing whether a given <TT
-CLASS="LITERAL"
->CYGNUM_HAL_EXCEPTION_*</TT
->
-definition is present. If it is present then its value is the vector
-that raises that exception. This does not need to be a one-to-one
-correspondence, and several <TT
-CLASS="LITERAL"
->CYGNUM_HAL_EXCEPTION_*</TT
->
-definitions may have the same value.</P
-><P
->Interrupt vectors are usually defined in the variant or platform
-HALs. The interrupt number space may either be continuous with the VSR
-number space, where they share a vector table (as in the i386) or may
-be a separate space where a separate decode stage is used (as in MIPS
-or PowerPC).</P
-></LI
-><LI
-><P
->Declare any static data used by the HAL to handle interrupts and
-exceptions. This is usually three vectors for interrupts:
-<TT
-CLASS="LITERAL"
->hal_interrupt_handlers[]</TT
->,
-<TT
-CLASS="LITERAL"
->hal_interrupt_data[]</TT
-> and
-<TT
-CLASS="LITERAL"
->hal_interrupt_objects[]</TT
->, which are sized according
-to the interrupt vector definitions. In addition a definition for the
-VSR table, <TT
-CLASS="LITERAL"
->hal_vsr_table[]</TT
-> should be made. These
-vectors are normally defined in either <TT
-CLASS="FILENAME"
->vectors.S</TT
->
-or <TT
-CLASS="FILENAME"
->hal_misc.c</TT
->.</P
-></LI
-><LI
-><P
->Define interrupt enable/disable macros. These are normally inline
-assembly fragments to execute the instructions, or manipulate the CPU
-register, that contains the CPU interrupt enable bit.</P
-></LI
-><LI
-><P
->A feature that many HALs support is the ability to execute DSRs on the
-interrupt stack. This is not an essential feature, and is better left
-unimplemented in the initial porting effort. If this is required, then
-the macro <TT
-CLASS="LITERAL"
->HAL_INTERRUPT_STACK_CALL_PENDING_DSRS()</TT
->
-should be defined to call a function in
-<TT
-CLASS="FILENAME"
->vectors.S</TT
->.</P
-></LI
-><LI
-><P
->Define the interrupt and VSR attachment macros. If the same arrays as
-for other HALs have been used for VSR and interrupt vectors, then
-these macro can be copied across unchanged.</P
-></LI
-></UL
-></LI
-><LI
-><P
->A number of other header files also need to be filled in:</P
-><P
-></P
-><UL
-><LI
-><P
-><TT
-CLASS="FILENAME"
->basetype.h</TT
->. This file defines the basic types
-used by eCos, together with the endianness and some other
-characteristics. This file only really needs to contain definitions
-if the architecture differs significantly from the defaults defined
-in <TT
-CLASS="FILENAME"
->cyg_type.h</TT
-></P
-></LI
-><LI
-><P
-><TT
-CLASS="FILENAME"
->hal_io.h</TT
->. This file contains macros for accessing
-device IO registers. If the architecture uses memory mapped IO, then
-these can be copied unchanged from an existing HAL such as MIPS. If
-the architecture uses special IO instructions, then these macros must
-be defined as inline assembler fragments. See the I386 HAL for an
-example. PCI bus access macros are usually defined in the variant or
-platform HALs.</P
-></LI
-><LI
-><P
-><TT
-CLASS="FILENAME"
->hal_cache.h</TT
->. This file contains cache access
-macros. If the architecture defines cache instructions, or control
-registers, then the access macros should be defined here. Otherwise
-they must be defined in the variant or platform HAL. Usually the cache
-dimensions (total size, line size, ways etc.) are defined in the
-variant HAL.</P
-></LI
-><LI
-><P
-><TT
-CLASS="FILENAME"
->arch.inc</TT
-> and
-<TT
-CLASS="FILENAME"
-><architecture>.inc</TT
->. These files are
-assembler headers used by <TT
-CLASS="FILENAME"
->vectors.S</TT
-> and
-<TT
-CLASS="FILENAME"
->context.S</TT
->.
-<TT
-CLASS="FILENAME"
-><architecture>.inc</TT
-> is a general purpose
-header that should contain things like register aliases, ABI
-definitions and macros useful to general assembly
-code. If there are no such definitions, then this file need not be
-provided. <TT
-CLASS="FILENAME"
->arch.inc</TT
-> contains macros for performing
-various eCos related operations such as initializing the CPU, caches,
-FPU etc. The definitions here may often be configured or overridden by
-definitions in the variant or platform HALs. See the MIPS HAL for an
-example of this.</P
-></LI
-></UL
-></LI
-><LI
-><P
->Write <TT
-CLASS="FILENAME"
->vectors.S</TT
->. This is the most important file
-in the HAL. It contains the CPU initialization code, exception and
-interrupt handlers. While other HALs should be consulted for
-structures and techniques, there is very little here that can be
-copied over without major edits.</P
-><P
->The main pieces of code that need to be defined here are:</P
-><P
-></P
-><UL
-><LI
-><P
->Reset vector. This usually need to be positioned at the start of the
-ROM or FLASH, so should be in a linker section of its own. It can then be
-placed correctly by the linker script. Normally this code is little
-more than a jump to the label <TT
-CLASS="LITERAL"
->_start</TT
->.</P
-></LI
-><LI
-><P
->Exception vectors. These are the trampoline routines connected to the
-hardware exception entry points that vector through the VSR table. In
-many architectures these are adjacent to the reset vector, and should
-occupy the same linker section. If the architecture allow the vectors
-to be moved then it may be necessary for these trampolines to be
-position independent so they can be relocated at runtime.</P
-><P
->The trampolines should do the minimum necessary to transfer control
-from the hardware vector to the VSR pointed to by the matching table
-entry. Exactly how this is done depends on the architecture. Usually
-the trampoline needs to get some working registers by either saving
-them to CPU special registers (e.g. PowerPC SPRs), using reserved
-general registers (MIPS K0 and K1), using only memory based
-operations (IA32), or just jumping directly (ARM). The VSR table index
-to be used is either implicit in the entry point taken (PowerPC, IA32,
-ARM), or must be determined from a CPU register (MIPS).</P
-></LI
-><LI
-><P
->Write kernel startup code. This is the location the reset vector jumps
-to, and can be in the main text section of the executable, rather than
-a special section. The code here should first initialize the CPU and other
-hardware subsystems. The best approach is to use a set of macro
-calls that are defined either in <TT
-CLASS="FILENAME"
->arch.inc</TT
-> or
-overridden in the variant or platform HALs. Other jobs that this code
-should do are: initialize stack pointer; copy the data section from
-ROM to RAM if necessary; zero the BSS; call variant and platform
-initializers; call <TT
-CLASS="FUNCTION"
->cyg_hal_invoke_constructors()</TT
->;
-call <TT
-CLASS="FUNCTION"
->initialize_stub()</TT
-> if necessary. Finally it
-should call <TT
-CLASS="FUNCTION"
->cyg_start()</TT
->. See <A
-HREF="hal-exception-handling.html#HAL-STARTUP"
->the Section called <I
->HAL Startup</I
-> in Chapter 10</A
-> for details.</P
-></LI
-><LI
-><P
->Write the default exception VSR. This VSR is installed in the VSR
-table for all synchronous exception vectors. See <A
-HREF="hal-default-synchronous-exception-handling.html"
->the Section called <I
->Default Synchronous Exception Handling</I
-> in Chapter 10</A
-> for details of
-what this VSR does.</P
-></LI
-><LI
-><P
->Write the default interrupt VSR. This is installed in all VSR table
-entries that correspond to external interrupts. See <A
-HREF="hal-default-synchronous-exception-handling.html"
->the Section called <I
->Default Synchronous Exception Handling</I
-> in Chapter 10</A
-> for details of
-what this VSR does.</P
-></LI
-><LI
-><P
->Write
-<TT
-CLASS="FUNCTION"
->hal_interrupt_stack_call_pending_dsrs()</TT
->. If this
-function is defined in <TT
-CLASS="FILENAME"
->hal_arch.h</TT
-> then it should
-appear here. The purpose of this function is to call DSRs on the
-interrupt stack rather than the current thread's stack. This is not an
-essential feature, and may be left until later. However it interacts
-with the stack switching that goes on in the interrupt VSR, so it may
-make sense to write these pieces of code at the same time to ensure
-consistency.</P
-><P
->When this function is implemented it should do the following:</P
-><P
-></P
-><UL
-><LI
-><P
->Take a copy of the current SP and then switch to the interrupt stack.</P
-></LI
-><LI
-><P
->Save the old SP, together with the CPU status register (or whatever
-register contains the interrupt enable status) and any other
-registers that may be corrupted by a function call (such as any link
-register) to locations in the interrupt stack.</P
-></LI
-><LI
-><P
->Enable interrupts.</P
-></LI
-><LI
-><P
->Call <TT
-CLASS="FUNCTION"
->cyg_interrupt_call_pending_DSRs()</TT
->. This is a
-kernel functions that actually calls any pending DSRs.</P
-></LI
-><LI
-><P
->Retrieve saved registers from the interrupt stack and switch back to
-the current thread stack.</P
-></LI
-><LI
-><P
->Merge the interrupt enable state recorded in the save CPU status
-register with the current value of the status register to restore the
-previous enable state. If the status register does not contain any
-other persistent state then this can be a simple restore of the
-register. However if the register contains other state bits that might
-have been changed by a DSR, then care must be taken not to disturb
-these.</P
-></LI
-></UL
-></LI
-><LI
-><P
->Define any data items needed. Typically <TT
-CLASS="FILENAME"
->vectors.S</TT
->
-may contain definitions for the VSR table, the interrupt tables and the
-interrupt stack. Sometimes these are only default definitions that may
-be overridden by the variant or platform HALs.</P
-></LI
-></UL
-></LI
-><LI
-><P
->Write <TT
-CLASS="FILENAME"
->context.S</TT
->. This file contains the context
-switch code. See <A
-HREF="hal-architecture-characterization.html#HAL-CONTEXT-SWITCH"
->the Section called <I
->Thread Context Switching</I
-> in Chapter 9</A
-> for details of
-how these functions operate. This file may also contain the
-implementation of <TT
-CLASS="FUNCTION"
->hal_setjmp()</TT
-> and
-<TT
-CLASS="FUNCTION"
->hal_longjmp()</TT
->.</P
-></LI
-><LI
-><P
->Write <TT
-CLASS="FILENAME"
->hal_misc.c</TT
->. This file contains any C
-data and functions needed by the HAL. These might include:</P
-><P
-></P
-><UL
-><LI
-><P
-><TT
-CLASS="VARNAME"
->hal_interrupt_*[]</TT
->. In some HALs, if these arrays
-are not defined in <TT
-CLASS="FILENAME"
->vectors.S</TT
-> then they must be
-defined here.</P
-></LI
-><LI
-><P
-><TT
-CLASS="FUNCTION"
->cyg_hal_exception_handler()</TT
->. This function is
-called from the exception VSR. It usually does extra decoding of the
-exception and invokes any special handlers for things like FPU traps,
-bus errors or memory exceptions. If there is nothing special to be
-done for an exception, then it either calls into the GDB stubs, by
-calling <TT
-CLASS="FUNCTION"
->__handle_exception()</TT
->, or
-invokes the kernel by calling
-<TT
-CLASS="FUNCTION"
->cyg_hal_deliver_exception()</TT
->.</P
-></LI
-><LI
-><P
-><TT
-CLASS="FUNCTION"
->hal_arch_default_isr()</TT
->. The
-<TT
-CLASS="VARNAME"
->hal_interrupt_handlers[]</TT
-> array is usually
-initialized with pointers to <TT
-CLASS="FILENAME"
->hal_default_isr()</TT
->,
-which is defined in the common HAL. This function handles things like
-Ctrl-C processing, but if that is not relevant, then it will call
-<TT
-CLASS="FUNCTION"
->hal_arch_default_isr()</TT
->. Normally this function
-should just return zero.</P
-></LI
-><LI
-><P
-><TT
-CLASS="FUNCTION"
->cyg_hal_invoke_constructors()</TT
->. This calls the
-constructors for all static objects before the program starts. eCos
-relies on these being called in the correct order for it to function
-correctly. The exact way in which constructors are handled may differ
-between architectures, although most use a simple table of function
-pointers between labels <TT
-CLASS="LITERAL"
->__CTOR_LIST__</TT
-> and
-<TT
-CLASS="LITERAL"
->__CTOR_END__</TT
-> which must called in order from the
-top down. Generally, this function can be copied directly from an
-existing architecture HAL.</P
-></LI
-><LI
-><P
->Bit indexing functions. If the macros
-<TT
-CLASS="LITERAL"
->HAL_LSBIT_INDEX()</TT
-> and
-<TT
-CLASS="LITERAL"
->HAL_MSBIT_INDEX()</TT
-> are defined as function calls,
-then the functions should appear here. The main reason for doing this
-is that the architecture does not have support for bit indexing and
-these functions must provide the functionality by conventional
-means. While the trivial implementation is a simple for loop, it is
-expensive and non-deterministic. Better, constant time,
-implementations can be found in several HALs (MIPS for example).</P
-></LI
-><LI
-><P
-><TT
-CLASS="FUNCTION"
->hal_delay_us()</TT
->. If the macro
-<TT
-CLASS="LITERAL"
->HAL_DELAY_US()</TT
-> is defined in <TT
-CLASS="FILENAME"
->hal_intr.h</TT
-> then it should be defined to
-call this function. While most of the time this function is called
-with very small values, occasionally (particularly in some ethernet
-drivers) it is called with values of several seconds. Hence the
-function should take care to avoid overflow in any calculations.</P
-></LI
-><LI
-><P
-><TT
-CLASS="FUNCTION"
->hal_idle_thread_action()</TT
->. This function is called
-from the idle thread via the
-<TT
-CLASS="LITERAL"
->HAL_IDLE_THREAD_ACTION()</TT
-> macro, if so
-defined. While normally this function does nothing, during development
-this is often a good place to report various important system
-parameters on LCDs, LED or other displays. This function can also
-monitor system state and report any anomalies. If the architecture
-supports a <TT
-CLASS="LITERAL"
->halt</TT
-> instruction then this is a good
-place to put an inline assembly fragment to execute it. It is also a
-good place to handle any power saving activity.</P
-></LI
-></UL
-></LI
-><LI
-><P
->Create the <TT
-CLASS="FILENAME"
-><architecture>.ld</TT
-> file. While
-this file may need to be moved to the variant HAL in the future, it
-should initially be defined here, and only moved if necessary.</P
-><P
->This file defines a set of macros that are used by the platform
-<TT
-CLASS="LITERAL"
->.ldi</TT
-> files to generate linker scripts. Most GCC
-toolchains are very similar so the correct approach is to copy the
-file from an existing architecture and edit it. The main things that
-will need editing are the <TT
-CLASS="LITERAL"
->OUTPUT_FORMAT()</TT
-> directive
-and maybe the creation or allocation of extra sections to various
-macros. Running the target linker with just the
-<TT
-CLASS="LITERAL"
->--verbose</TT
-> argument will cause it to output its
-default linker script. This can be compared with the
-<TT
-CLASS="LITERAL"
->.ld</TT
-> file and appropriate edits made.</P
-></LI
-><LI
-><P
->If GDB stubs are to be supported in RedBoot or eCos, then support must
-be included for these. The most important of these are <TT
-CLASS="FILENAME"
->include/<architecture>-stub.h</TT
-> and
-<TT
-CLASS="FILENAME"
->src/<architecture>-stub.c</TT
->. In all existing
-architecture HALs these files, and any support files they need, have
-been derived from files supplied in <TT
-CLASS="LITERAL"
->libgloss</TT
->, as
-part of the GDB toolchain package. If this is a totally new
-architecture, this may not have been done, and they must be created
-from scratch.</P
-><P
-><TT
-CLASS="FILENAME"
->include/<architecture>-stub.h</TT
->
-contains definitions that are used by the GDB stubs to describe the
-size, type, number and names of CPU registers. This information is
-usually found in the GDB support files for the architecture. It also
-contains prototypes for the functions exported by
-<TT
-CLASS="FILENAME"
->src/<architecture>-stub.c</TT
->; however, since
-this is common to all architectures, it can be copied from some other
-HAL.</P
-><P
-><TT
-CLASS="FILENAME"
->src/<architecture>-stub.c</TT
-> implements the
-functions exported by the header. Most of this is fairly straight
-forward: the implementation in existing HALs should show exactly what
-needs to be done. The only complex part is the support for
-single-stepping. This is used a lot by GDB, so it cannot be
-avoided. If the architecture has support for a trace or single-step
-trap then that can be used for this purpose. If it does not then this
-must be simulated by planting a breakpoint in the next
-instruction. This can be quite involved since it requires some
-analysis of the current instruction plus the state of the CPU to
-determine where execution is going to go next.</P
-></LI
-></OL
-></DIV
-><DIV
-CLASS="SECTION"
-><H2
-CLASS="SECTION"
-><A
-NAME="HAL-PORTING-ARCHITECTURE-CDL">CDL Requirements</H2
-><P
->The CDL needed for any particular architecture HAL depends to a large
-extent on the needs of that architecture. This includes issues such as
-support for different variants, use of FPUs, MMUs and caches. The
-exact split between the architecture, variant and platform HALs for
-various features is also somewhat fluid. </P
-><P
->To give a rough idea about how the CDL for an architecture is
-structured, we will take as an example the I386 CDL.</P
-><P
->This first section introduces the CDL package and placed it under the
-main HAL package. Include files from this package will be put in the
-<TT
-CLASS="FILENAME"
->include/cyg/hal</TT
-> directory, and definitions from
-this file will be placed in
-<TT
-CLASS="FILENAME"
->include/pkgconf/hal_i386.h</TT
->. The
-<TT
-CLASS="LITERAL"
->compile</TT
-> line specifies the files in the
-<TT
-CLASS="FILENAME"
->src</TT
-> directory that are to be compiled as part of
-this package.</P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->cdl_package CYGPKG_HAL_I386 {
- display "i386 architecture"
- parent CYGPKG_HAL
- hardware
- include_dir cyg/hal
- define_header hal_i386.h
- description "
- The i386 architecture HAL package provides generic
- support for this processor architecture. It is also
- necessary to select a specific target platform HAL
- package."
-
- compile hal_misc.c context.S i386_stub.c hal_syscall.c</PRE
-></TD
-></TR
-></TABLE
-><P
->Next we need to generate some files using non-standard make rules. The
-first is <TT
-CLASS="FILENAME"
->vectors.S</TT
->, which is not put into the
-library, but linked explicitly with all applications. The second is
-the generation of the <TT
-CLASS="FILENAME"
->target.ld</TT
-> file from
-<TT
-CLASS="FILENAME"
->i386.ld</TT
-> and the startup-selected
-<TT
-CLASS="FILENAME"
->.ldi</TT
-> file. Both of these are essentially
-boilerplate code that can be copied and edited.</P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
-> make {
- <PREFIX>/lib/vectors.o : <PACKAGE>/src/vectors.S
- $(CC) -Wp,-MD,vectors.tmp $(INCLUDE_PATH) $(CFLAGS) -c -o $@ $<
- @echo $@ ": \\" > $(notdir $@).deps
- @tail +2 vectors.tmp >> $(notdir $@).deps
- @echo >> $(notdir $@).deps
- @rm vectors.tmp
- }
-
- make {
- <PREFIX>/lib/target.ld: <PACKAGE>/src/i386.ld
- $(CC) -E -P -Wp,-MD,target.tmp -DEXTRAS=1 -xc $(INCLUDE_PATH) $(CFLAGS) -o $@ $<
- @echo $@ ": \\" > $(notdir $@).deps
- @tail +2 target.tmp >> $(notdir $@).deps
- @echo >> $(notdir $@).deps
- @rm target.tmp
- }</PRE
-></TD
-></TR
-></TABLE
-><P
->The i386 is currently the only architecture that supports SMP. The
-following CDL simply enabled the HAL SMP support if
-required. Generally this will get enabled as a result of a
-<TT
-CLASS="LITERAL"
->requires</TT
-> statement in the kernel. The
-<TT
-CLASS="LITERAL"
->requires</TT
-> statement here turns off lazy FPU
-switching in the FPU support code, since it is inconsistent with SMP
-operation.</P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
-> cdl_component CYGPKG_HAL_SMP_SUPPORT {
- display "SMP support"
- default_value 0
- requires { CYGHWR_HAL_I386_FPU_SWITCH_LAZY == 0 }
-
- cdl_option CYGPKG_HAL_SMP_CPU_MAX {
- display "Max number of CPUs supported"
- flavor data
- default_value 2
- }
- }</PRE
-></TD
-></TR
-></TABLE
-><P
->The i386 HAL has optional FPU support, which is enabled by default. It
-can be disabled to improve system performance. There are two FPU
-support options: either to save and restore the FPU state on every
-context switch, or to only switch the FPU state when necessary.</P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->
- cdl_component CYGHWR_HAL_I386_FPU {
- display "Enable I386 FPU support"
- default_value 1
- description "This component enables support for the
- I386 floating point unit."
-
- cdl_option CYGHWR_HAL_I386_FPU_SWITCH_LAZY {
- display "Use lazy FPU state switching"
- flavor bool
- default_value 1
-
- description "
- This option enables lazy FPU state switching.
- The default behaviour for eCos is to save and
- restore FPU state on every thread switch, interrupt
- and exception. While simple and deterministic, this
- approach can be expensive if the FPU is not used by
- all threads. The alternative, enabled by this option,
- is to use hardware features that allow the FPU state
- of a thread to be left in the FPU after it has been
- descheduled, and to allow the state to be switched to
- a new thread only if it actually uses the FPU. Where
- only one or two threads use the FPU this can avoid a
- lot of unnecessary state switching."
- }
- }</PRE
-></TD
-></TR
-></TABLE
-><P
->The i386 HAL also has support for different classes of CPU. In
-particular, Pentium class CPUs have extra functional units, and some
-variants of GDB expect more registers to be reported. These options
-enable these features. Generally these are enabled by
-<TT
-CLASS="LITERAL"
->requires</TT
-> statements in variant or platform
-packages, or in <TT
-CLASS="LITERAL"
->.ecm</TT
-> files.</P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
-> cdl_component CYGHWR_HAL_I386_PENTIUM {
- display "Enable Pentium class CPU features"
- default_value 0
- description "This component enables support for various
- features of Pentium class CPUs."
-
- cdl_option CYGHWR_HAL_I386_PENTIUM_SSE {
- display "Save/Restore SSE registers on context switch"
- flavor bool
- default_value 0
-
- description "
- This option enables SSE state switching. The default
- behaviour for eCos is to ignore the SSE registers.
- Enabling this option adds SSE state information to
- every thread context."
- }
-
- cdl_option CYGHWR_HAL_I386_PENTIUM_GDB_REGS {
- display "Support extra Pentium registers in GDB stub"
- flavor bool
- default_value 0
-
- description "
- This option enables support for extra Pentium registers
- in the GDB stub. These are registers such as CR0-CR4, and
- all MSRs. Not all GDBs support these registers, so the
- default behaviour for eCos is to not include them in the
- GDB stub support code."
- }
- }</PRE
-></TD
-></TR
-></TABLE
-><P
->In the i386 HALs, the linker script is provided by the architecture
-HAL. In other HALs, for example MIPS, it is provided in the variant
-HAL. The following option provides the name of the linker script to
-other elements in the configuration system.</P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
-> cdl_option CYGBLD_LINKER_SCRIPT {
- display "Linker script"
- flavor data
- no_define
- calculated { "src/i386.ld" }
- }</PRE
-></TD
-></TR
-></TABLE
-><P
->Finally, this interface indicates whether the platform supplied an
-implementation of the
-<TT
-CLASS="FUNCTION"
->hal_i386_mem_real_region_top()</TT
-> function. If it
-does then it will contain a line of the form: <TT
-CLASS="LITERAL"
->implements
-CYGINT_HAL_I386_MEM_REAL_REGION_TOP</TT
->. This allows packages
-such as RedBoot to detect the presence of this function so that they
-may call it.</P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
-> cdl_interface CYGINT_HAL_I386_MEM_REAL_REGION_TOP {
- display "Implementations of hal_i386_mem_real_region_top()"
- }
-
-}</PRE
-></TD
-></TR
-></TABLE
-></DIV
-></DIV
-><DIV
-CLASS="NAVFOOTER"
-><HR
-ALIGN="LEFT"
-WIDTH="100%"><TABLE
-SUMMARY="Footer navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
-><A
-HREF="hal-porting-variant.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="ecos-ref.html"
-ACCESSKEY="H"
->Home</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
-><A
-HREF="hal-future-developments.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->Variant HAL Porting</TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="hal-porting-guide.html"
-ACCESSKEY="U"
->Up</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
->Future developments</TD
-></TR
-></TABLE
-></DIV
-></BODY
-></HTML
->
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff